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

- Add VERSIONING.md documenting 0.1.x/0.2.x branch strategy
- Add docs/CHANGELOG.md with release notes for v0.1.0-v0.2.1
- Update CONTRIBUTING.md: fix master->main, add develop branch
- Closes #120
This commit is contained in:
shokollm
2026-04-05 09:38:25 +00:00
parent da0fa302de
commit 16e417c88e
3 changed files with 229 additions and 4 deletions

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