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:
71
VERSIONING.md
Normal file
71
VERSIONING.md
Normal 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
|
||||
Reference in New Issue
Block a user