Contributing

Contributing to project-brain

Thank you for contributing. This guide covers setup, tests, commit style, and PR guidelines.

Development Setup

git clone https://github.com/Srujan-Amaragatti05/project-brain
cd project-brain

# Windows
python -m venv env
env\Scripts\activate

# Linux / macOS
python3 -m venv env
source env/bin/activate

# Install with dev extras (includes pytest + pytest-cov)
pip install -e ".[dev]"

Tip

Use pip install -e ".[dev]" (not just pip install -e .) to get pytest and pytest-cov included.

Running Tests

pytest                          # run all 18 tests
pytest tests/test_cli.py        # run a specific test file
pytest --cov=project_brain      # with coverage report

Test files

File	Covers
`test_cli.py`	Core CLI commands
`test_analyzer.py`	AST analyzer
`test_diff.py`	Git diff logic
`test_config.py`	Config loader
`test_advanced_cli.py`	Edge cases for CLI
`test_advanced_config.py`	Config edge cases
`test_advanced_diff.py`	Diff edge cases
`test_advanced_export.py`	Export system
`test_advanced_explain.py`	Explain engine
`test_advanced_edge_cases.py`	Error handling
`test_advanced_logging.py`	Logging system

Contribution Guidelines

•Keep PRs focused on one change
•Preserve CLI consistency — no breaking changes to existing commands
•Add tests for any new behavior
•Avoid adding unnecessary dependencies
•Maintain local-first philosophy — no cloud calls without explicit opt-in
•Update documentation if behavior changes

Commit Style

feat: add semantic export filtering
fix: improve git diff handling for merge commits
docs: update README installation steps
test: add edge case for empty repository
refactor: split exporter into smaller modules

Recommended workflow

git checkout -b feature/my-feature    # create branch
# make your changes...
pytest                                # verify tests pass
git add .
git commit -m "feat: describe change"
git push origin feature/my-feature   # open PR

Before opening a PR

✓All tests pass (pytest)
✓CLI commands work end-to-end
✓Documentation updated if behavior changed
✓No new dependencies added without discussion

Open an Issue →Start a Discussion →

← brain community Architecture →