shoko/kugetsu
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: add versioning policy, changelog, and update contributing guide #149

Merged
shoko merged 2 commits from fix/issue-120 into main 2026-04-05 12:44:44 +02:00
Conversation 3 Commits 2 Files Changed 3 +229 -4
3 changed files with 229 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
CONTRIBUTING.md
View File

@@ -2,10 +2,10 @@
## Workflow
1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b docs/topic-name`
1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b feat/issue-N-feature-name`
han commented 2026-04-05 11:54:35 +02:00
Outdated
Review
Copy Link

the branch name should be fix/issue-N-bug-name or feat/issue-N-feature-name

the branch name should be fix/issue-N-bug-name or 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 `master` for reviewable changes
4. Do not merge directly to `main` or `develop` for reviewable changes
5. After approval, squash and merge
## Guidelines
@@ -14,10 +14,53 @@
- Keep PRs focused and reasonably sized
- Document any non-obvious decisions
- Test changes before submitting
- See [VERSIONING.md](VERSIONING.md) for backport compatibility rules
## Branches
- `master` — stable, reviewed content only
### 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
- `research/*` — new research notes
- `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

71
VERSIONING.md Normal file
View File

@@ -0,0 +1,71 @@
# Versioning Policy
## Branch Strategy
Kugetsu uses a dual-branch model:
| Branch | Purpose | Version | Stability |
|--------|---------|---------|-----------|
| `main` | Stable releases | 0.1.x | Production-ready |
| `develop` | Experimental work | 0.2.x | Active development |
### Branch Definitions
- **`main`**: Contains the latest stable 0.1.x releases. All changes here should be production-ready and backport-compatible when possible.
- **`develop`**: Contains work for the next major version (0.2.x). This branch may contain experimental features that could change or be removed.
## Version Format
Versions follow [Semantic Versioning](https://semver.org/):
```
MAJOR.MINOR.PATCH
```
- **MAJOR**: Incompatible API/behavior changes
- **MINOR**: New functionality (backward-compatible)
- **PATCH**: Bug fixes (backward-compatible)
## Backport Compatibility
### Backport-Compatible Changes (0.1.x)
- Bug fixes
- Documentation updates
- Performance improvements
- Adding new inputs/options (must have sensible defaults)
- Changes that only affect 0.2.x-specific features
### NOT Backport-Compatible
- Removing or renaming existing options
- Changing default values of existing options
- Changing behavior of existing commands
- Introducing breaking changes to the API/shell interface
## Deprecation Policy
When introducing breaking changes:
1. **Deprecate in minor X**: Add warning messages, document the change
2. **Remove in major X+1**: The breaking change is removed in the next major version
Example:
- Option `--old-flag` deprecated in v0.1.5
- Option `--old-flag` removed in v1.0.0 (not v0.2.0)
## What Constitutes a Version Bump
| Change Type | Version Bump |
|-------------|--------------|
| Add new command/option | MINOR |
| Bug fix | PATCH |
| Change default value | MINOR (may warrant PATCH) |
| Add new required input | MAJOR |
| Remove deprecated feature | MAJOR |
| Change behavior of existing command | MINOR (needs deprecation first) |
## Release Process
1. Changes are developed on feature branches
2. PRs are opened against `main` for 0.1.x changes, or `develop` for 0.2.x
3. After review and approval, changes are squash-merged
4. Releases are tagged from `main` after significant changes

111
docs/CHANGELOG.md Normal file
View File

@@ -0,0 +1,111 @@
# Changelog
All notable changes to kugetsu are documented here.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]
## [v0.2.1] - 2026-04-03
### Fixed
- Prevent excess agent spawning with flock + sequential processing
## [v0.2.0] - 2026-03-30
### Added
- Queue system with background daemon
- Agent timeout handling
- Context dump/load for session isolation
- PR tracking and safe destroy
## [v0.1.13] - 2026-03-29
### Fixed
- Add missing closing parenthesis in process_queue Python extraction
## [v0.1.12] - 2026-03-25
### Added
- Post-comment helper for PM agent
## [v0.1.11] - 2026-03-20
### Fixed
- Wrap cmd_continue in subshell with cd for correct worktree dir
## [v0.1.10] - 2026-03-15
### Fixed
- destroy --base now also deletes PM agent session
## [v0.1.9] - 2026-03-10
### Added
- init creates base session in ~/.kugetsu-worktrees
- Adds context to forked sessions
- Clears logs on init
## [v0.1.8] - 2026-03-05
### Fixed
- destroy --base and --pm-agent actually delete opencode sessions
## [v0.1.7] - 2026-02-28
### Fixed
- Warn if init run from non-empty directory
## [v0.1.6] - 2026-02-20
### Fixed
- Detect session via DB query instead of opencode session list
## [v0.1.5] - 2026-02-15
### Fixed
- Update forked session permissions after detection
## [v0.1.4] - 2026-02-10
### Fixed
- Call fix_session_permissions before forking
## [v0.1.3] - 2026-02-05
### Fixed
- Session detection ordering bug and debugging
## [v0.1.2] - 2026-01-28
### Fixed
- Improve session detection in cmd_start with retry logic and logging
## [v0.1.1] - 2026-01-20
### Fixed
- Use cd + worktree inside parent dir instead of --dir flag
## [v0.1.0] - 2026-01-15
### Added
- KUGETSU_VERBOSITY for PM agent output control
- Initial documented release
[Unreleased]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.1...HEAD
[v0.2.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.0...v0.2.1
[v0.2.0]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.13...v0.2.0
[v0.1.13]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.12...v0.1.13
[v0.1.12]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.11...v0.1.12
[v0.1.11]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.10...v0.1.11
[v0.1.10]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.9...v0.1.10
[v0.1.9]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.8...v0.1.9
[v0.1.8]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.7...v0.1.8
[v0.1.7]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.6...v0.1.7
[v0.1.6]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.5...v0.1.6
[v0.1.5]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.4...v0.1.5
[v0.1.4]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.3...v0.1.4
[v0.1.3]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.2...v0.1.3
[v0.1.2]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.1...v0.1.2
[v0.1.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.0...v0.1.1
[v0.1.0]: https://git.fbrns.co/shoko/kugetsu/releases/tag/v0.1.0