# 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