16e417c88e
- 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
72 lines
2.2 KiB
Markdown
72 lines
2.2 KiB
Markdown
# 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
|