# Contributing to Honcho

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](./README.md#local-development) in the README 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

## Pre-commit Hooks

Honcho uses pre-commit hooks to enforce code quality and consistency. They run linting, formatting, type checking, and security scans before each commit.

### Installation

```bash
uv add --dev pre-commit
uv run pre-commit install \
    --hook-type pre-commit \
    --hook-type commit-msg \
    --hook-type pre-push
```

### What the hooks do

- **Code Quality** — Python linting and formatting (ruff), TypeScript linting (biome)
- **Type Checking** — Static analysis with basedpyright
- **Security** — Vulnerability scanning with bandit
- **Documentation** — Markdown linting and license header checks
- **Testing** — Automated test runs for Python and TypeScript
- **File Hygiene** — Trailing whitespace, line endings, file size checks
- **Commit Standards** — Conventional commit message validation

### Manual execution

Run against all files without committing:

```bash
uv run pre-commit run --all-files
```

Run a specific hook:

```bash
uv run pre-commit run ruff --all-files
uv run pre-commit run basedpyright --all-files
```

## Coding Standards

### Python Code Style

- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines
- Use [ruff](https://docs.astral.sh/ruff/) for linting and code formatting
- 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, or integration)
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
- **Security issues** - Report **privately** only — see [`SECURITY.md`](./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! 🫡