kugetsu/CONTRIBUTING.md

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 for backport compatibility rules

Pre-commit Hooks

This repository uses pre-commit for linting and commit message enforcement.

Setup

pip install pre-commit
pre-commit install

Hooks

• shellcheck — Lints bash scripts
• ruff — Lints and formats Python
• commitizen — Enforces Conventional Commits 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 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