# StellaOps Versioning

This document describes the versioning strategy for StellaOps releases.

## Overview

StellaOps uses a two-tier versioning system:

1. **Suite Releases** - Ubuntu-style calendar versioning (YYYY.MM) with codenames
2. **Module Releases** - Semantic versioning (MAJOR.MINOR.PATCH)

---

## Suite Versions (Ubuntu-style)

### Format

```
YYYY.MM[-channel]
```

- **YYYY** - Four-digit year
- **MM** - Month (always `04` or `10`)
- **channel** - Optional: `edge`, `stable`, or `lts`

### Examples

| Version | Codename | Release Date | Type | Support |
|---------|----------|--------------|------|---------|
| 2026.04 | Nova | April 2026 | LTS | 5 years |
| 2026.10 | Orion | October 2026 | Feature | 9 months |
| 2027.04 | Pulsar | April 2027 | LTS | 5 years |
| 2027.10 | Quasar | October 2027 | Feature | 9 months |

### Release Cadence

- **April releases (XX.04)** - Long Term Support (LTS)
  - 5 years of security updates
  - 3 years of standard support
  - Recommended for production environments

- **October releases (XX.10)** - Feature releases
  - 9 months of support
  - Latest features and improvements
  - Recommended for development and testing

### Codenames

Codenames follow a celestial theme with alphabetical progression:

| Letter | Codename | Celestial Object |
|--------|----------|------------------|
| N | Nova | Exploding star |
| O | Orion | Constellation |
| P | Pulsar | Rotating neutron star |
| Q | Quasar | Distant active galaxy |
| R | Rigel | Blue supergiant star |
| S | Sirius | Brightest star |
| T | Triton | Neptune's moon |
| U | Umbra | Shadow region |
| V | Vega | Fifth-brightest star |
| W | Wezen | Delta Canis Majoris |

See [codenames.md](codenames.md) for the complete registry.

---

## Module Versions (Semantic Versioning)

### Format

```
MAJOR.MINOR.PATCH[-prerelease]
```

Following [Semantic Versioning 2.0.0](https://semver.org/):

- **MAJOR** - Incompatible API changes
- **MINOR** - New functionality (backwards-compatible)
- **PATCH** - Bug fixes (backwards-compatible)
- **prerelease** - Optional: `alpha.1`, `beta.2`, `rc.1`

### Examples

| Version | Description |
|---------|-------------|
| 1.0.0 | Initial stable release |
| 1.1.0 | New feature added |
| 1.1.1 | Bug fix |
| 2.0.0-alpha.1 | Breaking changes preview |
| 2.0.0-rc.1 | Release candidate |
| 2.0.0 | New major version |

### Module List

| Module | Package Name | Current Version |
|--------|--------------|-----------------|
| Authority | StellaOps.Authority | 1.0.0 |
| Attestor | StellaOps.Attestor | 1.0.0 |
| Concelier | StellaOps.Concelier | 1.0.0 |
| Scanner | StellaOps.Scanner | 1.0.0 |
| Policy | StellaOps.Policy | 1.0.0 |
| Signer | StellaOps.Signer | 1.0.0 |
| Excititor | StellaOps.Excititor | 1.0.0 |
| Gateway | StellaOps.Gateway | 1.0.0 |
| Scheduler | StellaOps.Scheduler | 1.0.0 |
| CLI | stellaops-cli | 1.0.0 |

---

## Compatibility Matrix

Each suite release documents which module versions are included:

### Suite 2026.04 "Nova" (Example)

| Module | Version | Breaking Changes |
|--------|---------|------------------|
| Authority | 1.0.0 | - |
| Attestor | 1.0.0 | - |
| Concelier | 1.0.0 | - |
| Scanner | 1.0.0 | - |
| Policy | 1.0.0 | - |
| Signer | 1.0.0 | - |
| Excititor | 1.0.0 | - |
| Gateway | 1.0.0 | - |
| Scheduler | 1.0.0 | - |
| CLI | 1.0.0 | - |

---

## Release Artifacts

### Suite Release Artifacts

| Artifact | Location |
|----------|----------|
| Container images | `git.stella-ops.org/stella-ops.org/{module}:{version}` |
| Helm chart | `stellaops-{version}.tgz` |
| CLI binaries | `stellaops-cli-{version}-{platform}.tar.gz` |
| Release manifest | `devops/releases/{version}.yaml` |
| Checksums | `SHA256SUMS-{version}.txt` |

### Module Release Artifacts

| Artifact | Location |
|----------|----------|
| NuGet packages | `git.stella-ops.org/api/packages/stella-ops.org/nuget/` |
| Container images | `git.stella-ops.org/stella-ops.org/{module}:{semver}` |

---

## Git Tags

### Suite Releases

```
suite-YYYY.MM[-codename]
```

Examples:
- `suite-2026.04`
- `suite-2026.04-nova`
- `suite-2026.10-orion`

### Module Releases

```
module-{name}-v{semver}
```

Examples:
- `module-authority-v1.0.0`
- `module-scanner-v1.2.3`
- `module-cli-v2.0.0-rc.1`

---

## Upgrade Path

### Supported Upgrades

| From | To | Notes |
|------|------|-------|
| N.04 | N.10 | Standard upgrade |
| N.10 | (N+1).04 | LTS upgrade |
| N.04 | (N+1).04 | LTS to LTS |
| N.04 | (N+2).04 | Skip-version upgrade (test thoroughly) |

### Migration Notes

Each suite release includes migration documentation in:
- `docs/releases/{version}/MIGRATION.md`
- `CHANGELOG.md`

---

## Related Documentation

- [Release Process](RELEASE_PROCESS.md)
- [Codename Registry](codenames.md)
- [CHANGELOG](../../CHANGELOG.md)