|
1 | 1 | # Contributing to Basic Memory |
2 | 2 |
|
3 | | -Thank you for considering contributing to Basic Memory! Your help is greatly appreciated to improve this project. |
| 3 | +Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the project and how to get started as a developer. |
4 | 4 |
|
5 | | -## How to Contribute |
| 5 | +## Getting Started |
6 | 6 |
|
7 | | -1. **Fork the Repo**: Fork the repository and clone your copy. |
8 | | -1. **Create a Branch**: Create a new branch for your feature or fix. |
9 | | -1. **Test Your Changes**: Ensure tests pass locally and include new tests when necessary to ensure 100& test coverage. |
10 | | -1. **Format Your Code**: Run `make format` to ensure code is formatted appropriately. |
11 | | -4. **Submit a PR**: Submit a pull request with a detailed description of your changes. |
| 7 | +### Development Environment |
12 | 8 |
|
13 | | -Thank You! |
| 9 | +1. **Clone the Repository**: |
| 10 | + ```bash |
| 11 | + git clone https://github.com/basicmachines-co/basic-memory.git |
| 12 | + cd basic-memory |
| 13 | + ``` |
| 14 | + |
| 15 | +2. **Install Dependencies**: |
| 16 | + ```bash |
| 17 | + # Using make (recommended) |
| 18 | + make install |
| 19 | + |
| 20 | + # Or using uv |
| 21 | + uv install -e ".[dev]" |
| 22 | + |
| 23 | + # Or using pip |
| 24 | + pip install -e ".[dev]" |
| 25 | + ``` |
| 26 | + |
| 27 | +3. **Run the Tests**: |
| 28 | + ```bash |
| 29 | + # Run all tests |
| 30 | + make test |
| 31 | + # or |
| 32 | + uv run pytest -p pytest_mock -v |
| 33 | + |
| 34 | + # Run a specific test |
| 35 | + pytest tests/path/to/test_file.py::test_function_name |
| 36 | + ``` |
| 37 | + |
| 38 | +### Development Workflow |
| 39 | + |
| 40 | +1. **Fork the Repo**: Fork the repository on GitHub and clone your copy. |
| 41 | +2. **Create a Branch**: Create a new branch for your feature or fix. |
| 42 | + ```bash |
| 43 | + git checkout -b feature/your-feature-name |
| 44 | + # or |
| 45 | + git checkout -b fix/issue-you-are-fixing |
| 46 | + ``` |
| 47 | +3. **Make Your Changes**: Implement your changes with appropriate test coverage. |
| 48 | +4. **Check Code Quality**: |
| 49 | + ```bash |
| 50 | + # Run all checks at once |
| 51 | + make check |
| 52 | + |
| 53 | + # Or run individual checks |
| 54 | + make lint # Run linting |
| 55 | + make format # Format code |
| 56 | + make type-check # Type checking |
| 57 | + ``` |
| 58 | +5. **Test Your Changes**: Ensure all tests pass locally and maintain 100% test coverage. |
| 59 | + ```bash |
| 60 | + make test |
| 61 | + ``` |
| 62 | +6. **Submit a PR**: Submit a pull request with a detailed description of your changes. |
| 63 | + |
| 64 | +## LLM-Assisted Development |
| 65 | + |
| 66 | +This project is designed for collaborative development between humans and LLMs (Large Language Models): |
| 67 | + |
| 68 | +1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs. This file contains: |
| 69 | + - Key project information and architectural overview |
| 70 | + - Development commands and workflows |
| 71 | + - Code style guidelines |
| 72 | + - Documentation standards |
| 73 | + |
| 74 | +2. **AI-Human Collaborative Workflow**: |
| 75 | + - We encourage using LLMs like Claude for code generation, reviews, and documentation |
| 76 | + - When possible, save context in markdown files that can be referenced later |
| 77 | + - This enables seamless knowledge transfer between different development sessions |
| 78 | + - Claude can help with implementation details while you focus on architecture and design |
| 79 | + |
| 80 | +3. **Adding to CLAUDE.md**: |
| 81 | + - If you discover useful project information or common commands, consider adding them to CLAUDE.md |
| 82 | + - This helps all contributors (human and AI) maintain consistent knowledge of the project |
| 83 | + |
| 84 | +## Pull Request Process |
| 85 | + |
| 86 | +1. **Create a Pull Request**: Open a PR against the `main` branch with a clear title and description. |
| 87 | +2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you create a PR. |
| 88 | +3. **PR Description**: Include: |
| 89 | + - What the PR changes |
| 90 | + - Why the change is needed |
| 91 | + - How you tested the changes |
| 92 | + - Any related issues (use "Fixes #123" to automatically close issues) |
| 93 | +4. **Code Review**: Wait for code review and address any feedback. |
| 94 | +5. **CI Checks**: Ensure all CI checks pass. |
| 95 | +6. **Merge**: Once approved, a maintainer will merge your PR. |
| 96 | + |
| 97 | +## Developer Certificate of Origin |
| 98 | + |
| 99 | +By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you certify that: |
| 100 | +- You have the right to submit your contributions |
| 101 | +- You're not knowingly submitting code with patent or copyright issues |
| 102 | +- Your contributions are provided under the project's license (AGPL-3.0) |
| 103 | + |
| 104 | +This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be properly incorporated into the project and potentially used in commercial applications. |
| 105 | + |
| 106 | +### Signing Your Commits |
| 107 | + |
| 108 | +You can sign your commits in one of two ways: |
| 109 | + |
| 110 | +1. **Using the `-s` or `--signoff` flag**: |
| 111 | + ```bash |
| 112 | + git commit -s -m "Your commit message" |
| 113 | + ``` |
| 114 | + This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO. |
| 115 | + |
| 116 | +2. **Configuring Git to automatically sign off**: |
| 117 | + ```bash |
| 118 | + git config --global alias.cs 'commit -s' |
| 119 | + ``` |
| 120 | + Then use `git cs -m "Your commit message"` to commit with sign-off. |
| 121 | + |
| 122 | +The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your agreement to the DCO. |
| 123 | + |
| 124 | +## Code Style Guidelines |
| 125 | + |
| 126 | +- **Python Version**: Python 3.12+ with full type annotations |
| 127 | +- **Line Length**: 100 characters maximum |
| 128 | +- **Formatting**: Use ruff for consistent styling |
| 129 | +- **Import Order**: Standard lib, third-party, local imports |
| 130 | +- **Naming**: Use snake_case for functions/variables, PascalCase for classes |
| 131 | +- **Documentation**: Add docstrings to public functions, classes, and methods |
| 132 | +- **Type Annotations**: Use type hints for all functions and methods |
| 133 | + |
| 134 | +## Testing Guidelines |
| 135 | + |
| 136 | +- **Coverage Target**: We aim for 100% test coverage for all code |
| 137 | +- **Test Framework**: Use pytest for unit and integration tests |
| 138 | +- **Mocking**: Use pytest-mock for mocking dependencies |
| 139 | +- **Edge Cases**: Test both normal operation and edge cases |
| 140 | +- **Database Testing**: Use in-memory SQLite for testing database operations |
| 141 | +- **Fixtures**: Use pytest fixtures for setup and teardown |
| 142 | + |
| 143 | +## Creating Issues |
| 144 | + |
| 145 | +If you're planning to work on something, please create an issue first to discuss the approach. Include: |
| 146 | + |
| 147 | +- A clear title and description |
| 148 | +- Steps to reproduce if reporting a bug |
| 149 | +- Expected behavior vs. actual behavior |
| 150 | +- Any relevant logs or screenshots |
| 151 | +- Your proposed solution, if you have one |
14 | 152 |
|
15 | 153 | ## Code of Conduct |
16 | 154 |
|
17 | 155 | All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). |
| 156 | + |
| 157 | +## Thank You! |
| 158 | + |
| 159 | +Your contributions help make Basic Memory better for everyone. We appreciate your time and effort! |
0 commit comments