177 lines
6.1 KiB
Plaintext
177 lines
6.1 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.
|
|
|
|
## 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](http://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
|
|
- Any relevant issue numbers (use "Closes #123" to auto-close issues)
|
|
- 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 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](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! 🫡
|