stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Refactor code structure and optimize performance across multiple modules

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-26 20:03:22 +02:00
parent c786faae84
commit f10d83c444
1385 changed files with 69732 additions and 10280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
docs/releases/RELEASE_PROCESS.md Normal file
View File

@@ -0,0 +1,255 @@
# StellaOps Release Process
This document describes the release process for StellaOps suite and module releases.
## Overview
StellaOps uses automated CI/CD pipelines for releases:
| Release Type | Workflow | Trigger |
|--------------|----------|---------|
| Module | `.gitea/workflows/module-publish.yml` | Tag or manual dispatch |
| Suite | `.gitea/workflows/release-suite.yml` | Tag or manual dispatch |
---
## Module Release Process
### Prerequisites
- [ ] All tests passing on main branch
- [ ] CHANGELOG.md updated with changes
- [ ] Version bumped in module's `version.txt` (if applicable)
- [ ] Breaking changes documented
### Steps
#### Option A: Tag-based Release
```bash
# Create and push tag
git tag module-authority-v1.2.3
git push origin module-authority-v1.2.3
```
The pipeline will automatically:
1. Parse module name and version from tag
2. Build the module
3. Publish NuGet package to Gitea registry
4. Build and push container image (if applicable)
#### Option B: Manual Dispatch
1. Navigate to **Actions** > **Module Publish**
2. Click **Run workflow**
3. Select:
- **Module**: e.g., `Authority`
- **Version**: e.g., `1.2.3`
- **Publish NuGet**: `true`
- **Publish Container**: `true`
4. Click **Run**
### Artifacts Published
| Artifact | Location |
|----------|----------|
| NuGet | `git.stella-ops.org/api/packages/stella-ops.org/nuget/index.json` |
| Container | `git.stella-ops.org/stella-ops.org/{module}:{version}` |
---
## Suite Release Process
### Prerequisites
- [ ] All module versions finalized
- [ ] Integration tests passing
- [ ] Security scan completed
- [ ] CHANGELOG.md updated
- [ ] Compatibility matrix documented
- [ ] Codename selected (see [codenames.md](codenames.md))
### Pre-Release Checklist
```markdown
- [ ] All P1 issues resolved
- [ ] Performance benchmarks meet SLOs
- [ ] Documentation updated
- [ ] Migration guide prepared
- [ ] Release notes drafted
- [ ] Security advisory review complete
- [ ] Air-gap bundle tested
- [ ] Helm chart validated
```
### Steps
#### Option A: Tag-based Release
```bash
# Create and push tag
git tag suite-2026.04-nova
git push origin suite-2026.04-nova
```
#### Option B: Manual Dispatch
1. Navigate to **Actions** > **Suite Release**
2. Click **Run workflow**
3. Fill in:
- **Version**: e.g., `2026.04`
- **Codename**: e.g., `Nova`
- **Channel**: `edge`, `stable`, or `lts`
- **Skip tests**: `false` (default)
- **Dry run**: `false` for actual release
4. Click **Run**
### Pipeline Stages
```
validate → test-gate → build-modules → build-containers
↘ ↓
build-cli → build-helm → release-manifest → create-release → summary
```
1. **Validate** - Check version format, resolve inputs
2. **Test Gate** - Run unit, architecture, and contract tests
3. **Build Modules** - Build all 9 modules (matrix)
4. **Build Containers** - Push container images (9 modules)
5. **Build CLI** - Build for 5 platforms
6. **Build Helm** - Package Helm chart
7. **Release Manifest** - Generate `suite-{version}.yaml`
8. **Create Release** - Create Gitea release with artifacts
9. **Summary** - Generate summary report
### Artifacts Published
| Artifact | Files |
|----------|-------|
| Container images | 9 modules × 3 tags (version, channel, latest) |
| CLI binaries | 5 platforms (linux-x64, linux-arm64, win-x64, osx-x64, osx-arm64) |
| Helm chart | `stellaops-{version}.tgz` |
| Release manifest | `suite-{version}.yaml` |
| Checksums | `SHA256SUMS-{version}.txt` |
---
## Release Channels
### Edge
- Pre-release builds
- May contain experimental features
- Not recommended for production
- Triggered by: `channel: edge` or tag without `-stable`/`-lts`
### Stable
- Production-ready releases
- Thoroughly tested
- 9 months of support (feature releases)
- Triggered by: `channel: stable`
### LTS (Long Term Support)
- April releases only (XX.04)
- 5 years of security updates
- 3 years of standard support
- Triggered by: `channel: lts`
---
## Rollback Procedures
### Container Rollback
```bash
# Pull previous version
docker pull git.stella-ops.org/stella-ops.org/authority:2025.10
# Update deployment
kubectl set image deployment/authority authority=git.stella-ops.org/stella-ops.org/authority:2025.10
```
### Helm Rollback
```bash
# List releases
helm history stellaops
# Rollback to previous revision
helm rollback stellaops 1
```
### Database Rollback
1. Stop all services
2. Restore database from backup
3. Deploy previous version
4. Verify data integrity
**Important**: Always test rollback procedures in staging before production.
---
## Hotfix Process
For critical security fixes:
1. Create hotfix branch from release tag
```bash
git checkout -b hotfix/2026.04.1 suite-2026.04
```
2. Apply fix and test
3. Tag hotfix release
```bash
git tag suite-2026.04.1
git push origin suite-2026.04.1
```
4. Cherry-pick fix to main branch
---
## Post-Release Tasks
- [ ] Verify artifacts in registry
- [ ] Update documentation site
- [ ] Send release announcement
- [ ] Update compatibility matrix
- [ ] Monitor for issues (24-48 hours)
- [ ] Update roadmap
---
## Troubleshooting
### Build Failures
1. Check test results in artifacts
2. Review workflow logs
3. Verify secrets are configured (GITEA_TOKEN)
### Push Failures
1. Verify registry authentication
2. Check network connectivity
3. Ensure no conflicting tags exist
### Common Issues
| Issue | Resolution |
|-------|------------|
| Tag already exists | Delete tag and recreate, or use next version |
| NuGet push fails | Check package already exists, use `--skip-duplicate` |
| Container push fails | Verify registry login, check image size limits |
---
## Related Documentation
- [Versioning Strategy](VERSIONING.md)
- [Codename Registry](codenames.md)
- [CI/CD Workflows](../../.gitea/workflows/)

202
docs/releases/VERSIONING.md Normal file
View File

@@ -0,0 +1,202 @@
# 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)

81
docs/releases/codenames.md Normal file
View File

@@ -0,0 +1,81 @@
# StellaOps Release Codenames
Codenames for StellaOps suite releases follow a celestial theme, progressing alphabetically.
## Codename Registry
### Planned Releases
| Version | Codename | Object Type | Description | Status |
|---------|----------|-------------|-------------|--------|
| 2026.04 | Nova | Star | Cataclysmic nuclear explosion on a white dwarf | Planned |
| 2026.10 | Orion | Constellation | The Hunter, prominent winter constellation | Planned |
| 2027.04 | Pulsar | Neutron Star | Highly magnetized rotating neutron star | Planned |
| 2027.10 | Quasar | Galaxy | Extremely luminous active galactic nucleus | Planned |
| 2028.04 | Rigel | Star | Blue supergiant, brightest star in Orion | Planned |
| 2028.10 | Sirius | Star | Brightest star in the night sky | Planned |
| 2029.04 | Triton | Moon | Largest moon of Neptune | Planned |
| 2029.10 | Umbra | Shadow | Darkest part of a shadow (solar eclipse) | Planned |
| 2030.04 | Vega | Star | Fifth-brightest star, in Lyra constellation | Planned |
| 2030.10 | Wezen | Star | Delta Canis Majoris, bright supergiant | Planned |
### Released Versions
| Version | Codename | Release Date | EOL Date | Notes |
|---------|----------|--------------|----------|-------|
| - | - | - | - | No releases yet |
## Naming Conventions
### Rules
1. **Alphabetical progression** - Each release uses the next letter
2. **Celestial theme** - All names relate to astronomical objects
3. **Single word** - Keep codenames to one word
4. **Pronounceable** - Names should be easy to say and remember
5. **Unique** - No repeated codenames in the registry
### Object Types
| Category | Examples |
|----------|----------|
| Stars | Nova, Sirius, Vega, Rigel |
| Constellations | Orion, Lyra, Cygnus |
| Galaxies | Quasar, Andromeda |
| Moons | Triton, Europa, Titan |
| Phenomena | Umbra, Aurora, Zenith |
| Neutron Stars | Pulsar, Magnetar |
## Future Codenames (Reserved)
Letters after W for future use:
| Letter | Candidate | Object Type |
|--------|-----------|-------------|
| X | Xena | Dwarf planet (informal name for Eris) |
| Y | Ymir | Saturn's moon |
| Z | Zenith | Astronomical position |
| A (cycle 2) | Andromeda | Galaxy |
| B (cycle 2) | Betelgeuse | Star |
| C (cycle 2) | Cygnus | Constellation |
## Usage in Release Notes
When referencing a release, use:
```
StellaOps 2026.04 "Nova"
```
Or in formal documentation:
```
StellaOps Suite Release 2026.04 (Codename: Nova)
```
## History
The celestial naming theme was chosen to reflect:
- **Reliability** - Like stars that guide navigation
- **Scope** - The vast scale of supply chain security challenges
- **Innovation** - Exploring new frontiers in software security