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:
-
Set up your development environment - Follow the Local Development guide in the Honcho repository to get Honcho running locally.
-
Join our community - Feel free to join us in our Discord to discuss your changes, get help, or ask questions.
-
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
- Fork the repository on GitHub
- Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/honcho.git
cd honcho
- 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
-
Push your branch to your fork:
git push origin your-branch-name
-
Create a pull request on GitHub from your branch to the main
branch
-
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
- Automated checks - Your PR will run through automated checks including tests and linting
- Project maintainer review - A project maintainer will review your code for:
- Code quality and adherence to standards
- Functionality and correctness
- Test coverage
- Documentation completeness
- Discussion and iteration - You may be asked to make changes or clarifications
- 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:
- Check if the issue already exists
- Use the appropriate issue template
- Provide clear reproduction steps for bugs
- Include relevant environment information
- 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! 🫡