195 lines
7.9 KiB
Plaintext
195 lines
7.9 KiB
Plaintext
---
|
|
title: 'Contributing Guidelines'
|
|
icon: 'handshake'
|
|
---
|
|
|
|
Thank you for your interest in contributing to Honcho! This guide outlines the process for contributing to the project and our development conventions.
|
|
|
|
## Before you write code
|
|
|
|
**Every pull request needs an issue, and that issue needs the `maintainer-approved` label.**
|
|
|
|
A pull request that is not linked to an approved issue gets labelled `needs-approved-issue`, with a comment explaining why. You then have 72 hours to link one before it is closed automatically. Reopening costs nothing once the link is in place. This is automated. We do this because an unreviewable backlog helps nobody: a PR against an unapproved issue is work you did that we may not be able to merge, no matter how good it is.
|
|
|
|
So, in order:
|
|
|
|
1. **Find approved work.** Browse [issues labelled `maintainer-approved`](https://github.com/plastic-labs/honcho/issues?q=is%3Aissue+is%3Aopen+label%3Amaintainer-approved). That label is the queue of things we have agreed should be built. Anything in it is fair game — comment on the issue to claim it.
|
|
|
|
2. **Or open an issue and get it approved.** Use the [issue templates](https://github.com/plastic-labs/honcho/issues/new/choose). Maintainers triage and apply the label.
|
|
|
|
3. **If you feel strongly about an issue, come to [Discord](https://discord.gg/honcho).** This is the fastest path by a wide margin. Maintainers are more active there than in the issue tracker, and a five-minute conversation about what you want to build usually resolves whether it fits before either side spends real time on it.
|
|
|
|
4. **Then open the PR** and link the issue — either `Fixes #123` in the description, or **Development → link an issue** in the sidebar. Both work.
|
|
|
|
Small exceptions we will not be pedantic about: fixing a typo, a broken link, or an obviously wrong code sample. Open the PR, explain it in one line, and we will sort out the issue linkage.
|
|
|
|
## Getting Started
|
|
|
|
Before you start contributing, please:
|
|
|
|
1. **Set up your development environment** - Follow the [Local Development guide](https://github.com/plastic-labs/honcho/blob/main/CONTRIBUTING.md#local-development) in the Honcho repository to get Honcho running locally.
|
|
|
|
2. **Join our community** - Feel free to join us in our [Discord](https://discord.gg/honcho) to discuss your changes, get help, or ask questions.
|
|
|
|
3. **Review existing issues** - Check the [issues tab](https://github.com/plastic-labs/honcho/issues) to see what's already being worked on or to find something to contribute to.
|
|
|
|
## Contribution Workflow
|
|
|
|
### 1. Fork and Clone
|
|
|
|
1. Fork the repository on GitHub
|
|
2. Clone your fork locally:
|
|
```bash
|
|
git clone https://github.com/YOUR_USERNAME/honcho.git
|
|
cd honcho
|
|
```
|
|
3. Add the upstream repository as a remote:
|
|
```bash
|
|
git remote add upstream https://github.com/plastic-labs/honcho.git
|
|
```
|
|
|
|
### 2. Create a Branch
|
|
|
|
Create a new branch for your feature or bug fix:
|
|
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
# or
|
|
git checkout -b fix/your-bug-fix-name
|
|
```
|
|
|
|
**Branch naming conventions:**
|
|
- `feature/description` - for new features
|
|
- `fix/description` - for bug fixes
|
|
- `docs/description` - for documentation updates
|
|
- `refactor/description` - for code refactoring
|
|
- `test/description` - for adding or updating tests
|
|
|
|
### 3. Make Your Changes
|
|
|
|
- Write clean, readable code that follows our coding standards (see below)
|
|
- Add tests for new functionality
|
|
- Update documentation as needed
|
|
- Make sure your changes don't break existing functionality
|
|
|
|
### 4. Commit Your Changes
|
|
|
|
We follow conventional commit standards. Format your commit messages as:
|
|
|
|
```
|
|
type(scope): description
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
**Types:**
|
|
- `feat`: A new feature
|
|
- `fix`: A bug fix
|
|
- `docs`: Documentation only changes
|
|
- `style`: Changes that do not affect the meaning of the code
|
|
- `refactor`: A code change that neither fixes a bug nor adds a feature
|
|
- `test`: Adding missing tests or correcting existing tests
|
|
- `chore`: Changes to the build process or auxiliary tools
|
|
|
|
**Examples:**
|
|
```bash
|
|
git commit -m "feat(api): add new dialectic endpoint for user insights"
|
|
git commit -m "fix(db): resolve connection pool timeout issue"
|
|
git commit -m "docs(readme): update installation instructions"
|
|
```
|
|
|
|
### 5. Submit a Pull Request
|
|
|
|
1. Push your branch to your fork:
|
|
```bash
|
|
git push origin your-branch-name
|
|
```
|
|
|
|
2. Create a pull request on GitHub from your branch to the `main` branch
|
|
|
|
3. Fill out the pull request template with:
|
|
- A clear description of what changes you've made
|
|
- The motivation for the changes
|
|
- A link to the approved issue — `Fixes #123` in the description, or **Development → link an issue** in the sidebar. This is required; see [Before you write code](#before-you-write-code).
|
|
- Screenshots or examples if applicable
|
|
|
|
## Coding Standards
|
|
|
|
### Python Code Style
|
|
|
|
- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines
|
|
- Use [Black](https://black.readthedocs.io/) for code formatting (we may add this to CI in the future)
|
|
- Use type hints where possible
|
|
- Write docstrings for functions and classes using Google style docstrings
|
|
|
|
### Code Organization
|
|
|
|
- Keep functions focused and single-purpose
|
|
- Use meaningful variable and function names
|
|
- Add comments for complex logic
|
|
- Follow existing patterns in the codebase
|
|
|
|
### Testing
|
|
|
|
- Write unit tests for new functionality
|
|
- Ensure existing tests pass before submitting
|
|
- Use descriptive test names that explain what is being tested
|
|
- Mock external dependencies appropriately
|
|
|
|
### Documentation
|
|
|
|
- Update relevant documentation for new features
|
|
- Include examples in docstrings where helpful
|
|
- Keep README and other docs up to date with changes
|
|
|
|
## Review Process
|
|
|
|
1. **Automated checks** - Your PR will run through automated checks including tests, linting, and the issue gate
|
|
2. **Project maintainer review** - A project maintainer will review your code for:
|
|
- Code quality and adherence to standards
|
|
- Functionality and correctness
|
|
- Test coverage
|
|
- Documentation completeness
|
|
3. **Discussion and iteration** - You may be asked to make changes or clarifications
|
|
4. **Approval and merge** - Once approved, your PR will be merged into `main`
|
|
|
|
## Types of Contributions
|
|
|
|
We welcome various types of contributions:
|
|
|
|
- **Bug fixes** - Help us squash bugs and improve stability
|
|
- **New features** - Add functionality that benefits the community
|
|
- **Documentation** - Improve or expand our documentation
|
|
- **Tests** - Increase test coverage and reliability
|
|
- **Performance improvements** - Help make Honcho faster and more efficient
|
|
- **Examples and tutorials** - Help other developers use Honcho
|
|
|
|
## Issue Reporting
|
|
|
|
When reporting bugs or requesting features:
|
|
|
|
1. Check if the issue already exists
|
|
2. Use the appropriate [issue template](https://github.com/plastic-labs/honcho/issues/new/choose) (bug, memory/recall quality, feature, integration, or documentation)
|
|
3. Provide clear reproduction steps for bugs
|
|
4. Include relevant environment information (managed vs self-hosted, server version, SDK)
|
|
5. Be specific about expected vs actual behavior
|
|
6. Redact secrets, JWTs, and production user content
|
|
|
|
## Questions and Support
|
|
|
|
- **General questions** - Join our [Discord](https://discord.gg/honcho)
|
|
- **Bug reports** - GitHub issues → Bug report template
|
|
- **Memory / recall quality** - GitHub issues → Memory / recall quality template
|
|
- **Feature requests** - GitHub issues → Feature request template
|
|
- **Integrations / plugins / app-store listings** - GitHub issues → Integration request template
|
|
- **Documentation issues** - GitHub issues → Documentation issue template
|
|
- **Security issues** - Report **privately** only — see [`SECURITY.md`](https://github.com/plastic-labs/honcho/blob/main/SECURITY.md) (GitHub Private Vulnerability Reporting or email). Do not open a public issue.
|
|
|
|
## License
|
|
|
|
By contributing to Honcho, you agree that your contributions will be licensed under the same [AGPL-3.0 License](./license) that covers the project.
|
|
|
|
Thank you for helping make Honcho better! 🫡
|