99 lines
2.5 KiB
Markdown
99 lines
2.5 KiB
Markdown
# Contributing
|
|
|
|
## Workflow
|
|
|
|
1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b feat/issue-N-feature-name`
|
|
2. Make changes and commit with clear messages
|
|
3. Open a Pull Request for review
|
|
4. Do not merge directly to `main` or `develop` for reviewable changes
|
|
5. After approval, squash and merge
|
|
|
|
## Guidelines
|
|
|
|
- Use clear, descriptive commit messages
|
|
- Keep PRs focused and reasonably sized
|
|
- Document any non-obvious decisions
|
|
- Test changes before submitting
|
|
- See [VERSIONING.md](VERSIONING.md) for backport compatibility rules
|
|
|
|
## Pre-commit Hooks
|
|
|
|
This repository uses [pre-commit](https://pre-commit.com/) for linting and commit message enforcement.
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
pip install pre-commit
|
|
pre-commit install
|
|
```
|
|
|
|
### Hooks
|
|
|
|
- **shellcheck** — Lints bash scripts
|
|
- **ruff** — Lints and formats Python
|
|
- **commitizen** — Enforces [Conventional Commits](https://www.conventionalcommits.org/) format
|
|
|
|
### Commit Message Format
|
|
|
|
Use Conventional Commits format:
|
|
|
|
```
|
|
type(scope): message
|
|
|
|
# Examples
|
|
fix(session): handle missing session gracefully
|
|
feat(pm): add queue daemon for task delegation
|
|
docs: update contributing guide
|
|
```
|
|
|
|
Types: `fix`, `feat`, `docs`, `refactor`, `chore`, `test`
|
|
|
|
## Branches
|
|
|
|
### Primary Branches
|
|
|
|
- `main` — stable 0.1.x releases, production-ready code
|
|
- `develop` — experimental 0.2.x work, next major version
|
|
|
|
### Feature Branches
|
|
|
|
- `fix/*` — bug fixes
|
|
- `feat/*` — new features
|
|
- `docs/*` — documentation updates
|
|
- `refactor/*` — code refactoring (no behavior change)
|
|
|
|
## Branch Model
|
|
|
|
```
|
|
main (0.1.x stable)
|
|
└── v0.1.0, v0.1.1, v0.1.2, ...
|
|
|
|
develop (0.2.x experimental)
|
|
└── (next major version work)
|
|
```
|
|
|
|
### Which Branch to Target?
|
|
|
|
| Change Type | Target Branch | Backport? |
|
|
|-------------|---------------|-----------|
|
|
| Bug fix | `main` | N/A |
|
|
| Documentation | `main` | N/A |
|
|
| New feature (backport-compatible) | `main` | Can cherry-pick to `develop` |
|
|
| Experimental feature | `develop` | No |
|
|
| Breaking change | `develop` | No |
|
|
|
|
## Backport Compatibility
|
|
|
|
Before merging, consider if your change is backport-compatible:
|
|
|
|
- **YES**: Bug fixes, docs, adding new optional inputs
|
|
- **NO**: Changing behavior, changing defaults, removing features
|
|
|
|
See [VERSIONING.md](VERSIONING.md) for full policy.
|
|
|
|
## Release Process
|
|
|
|
1. Bug fixes and docs → directly to `main`
|
|
2. New features → `develop` or feature branches → `develop`
|
|
3. When `develop` is stable enough → merge to `main` for release
|