Thank you for your interest in contributing to Honcho! This guide outlines the process for contributing to the project and our development conventions.

​
Getting Started

Before you start contributing, please:
  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

Create a new branch for your feature or bug fix: 
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: 
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
    • Any relevant issue numbers (use “Closes #123” to auto-close issues)
    • 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 and linting
  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
  3. Provide clear reproduction steps for bugs
  4. Include relevant environment information
  5. Be specific about expected vs actual behavior

​
Questions and Support

  • General questions - Join our Discord
  • Bug reports - Use GitHub issues
  • Feature requests - Use GitHub issues with the feature request template
  • Security issues - Please email us privately rather than opening a public issue

​
License

By contributing to Honcho, you agree that your contributions will be licensed under the same AGPL-3.0 License that covers the project. Thank you for helping make Honcho better! 🫡