Contributing Guidelines

​

Before you write code

1. Find approved work. Browse issues labelled maintainer-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. Maintainers triage and apply the label.
3. If you feel strongly about an issue, come to Discord. 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.

​

Getting Started

1. Set up your development environment - Follow the Local Development guide in the Honcho repository to get Honcho running locally.
2. Join our community - Feel free to join us in our Discord to discuss your changes, get help, or ask questions.
3. Review existing issues - Check the issues tab 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:
   git clone https://github.com/YOUR_USERNAME/honcho.git
   cd honcho
   
3. Add the upstream repository as a remote:
   git remote add upstream https://github.com/plastic-labs/honcho.git
   

​

2. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix-name

• 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

type(scope): description

[optional body]

[optional footer]

• 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

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:
   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.
   • Screenshots or examples if applicable

​

Coding Standards

​

Python Code Style

• Follow PEP 8 style guidelines
• Use Black 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

• 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

1. Check if the issue already exists
2. Use the appropriate issue template (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
• 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 (GitHub Private Vulnerability Reporting or email). Do not open a public issue.

​

License