# Releasing rpm-ostree

## Overview

This document describes the release process for rpm-ostree, including versioning strategy, release preparation, and publication procedures. Following these guidelines ensures consistent and reliable releases.

## Versioning Strategy

### Semantic Versioning

rpm-ostree follows [Semantic Versioning](https://semver.org/) (SemVer) with the format `MAJOR.MINOR.PATCH`:

- **MAJOR**: Incompatible API changes
- **MINOR**: New functionality in a backward-compatible manner
- **PATCH**: Backward-compatible bug fixes

### Version Examples
```
2023.8         # Major release (year.month)
2023.8.1       # Patch release
2023.8.2       # Another patch release
2024.1         # Next major release
```

### Pre-release Versions
```
2023.8-rc1     # Release candidate
2023.8-beta1   # Beta release
2023.8-alpha1  # Alpha release
```

## Release Planning

### Release Schedule

#### Regular Release Cycle
- **Major releases**: Quarterly (every 3 months)
- **Minor releases**: Monthly
- **Patch releases**: As needed for critical fixes
- **Pre-releases**: 2-4 weeks before major releases

#### Release Timeline
```
Week 1-2: Feature freeze and testing
Week 3: Release candidate preparation
Week 4: Final testing and release
```

### Release Criteria

#### Feature Completeness
- All planned features implemented
- Documentation updated
- Tests passing
- No known critical bugs

#### Quality Assurance
- All tests passing
- Performance benchmarks met
- Security audit completed
- Compatibility verified

#### Documentation
- Release notes prepared
- API documentation updated
- User documentation current
- Migration guide available (if needed)

## Release Preparation

### Pre-release Checklist

#### Code Quality
```bash
# Run all tests
make check
make check-integration

# Run performance tests
make check-performance

# Run security tests
make check-security

# Code quality checks
make lint
make static-analysis
make format-check
```

#### Documentation
```bash
# Update version numbers
sed -i 's/VERSION=.*/VERSION=2023.8/' configure.ac
sed -i 's/version = ".*"/version = "2023.8"/' rust/Cargo.toml

# Update release notes
vim NEWS.md

# Update documentation
make docs
```

#### Build Verification
```bash
# Clean build
make distclean
./autogen.sh
make

# Test installation
sudo make install
sudo make uninstall

# Test packaging
make dist
```

### Release Branch Management

#### Creating Release Branch
```bash
# Create release branch
git checkout -b release-2023.8

# Cherry-pick fixes
git cherry-pick <commit-hash>

# Update version
git add configure.ac rust/Cargo.toml NEWS.md
git commit -m "Bump version to 2023.8"
```

#### Release Candidate Process
```bash
# Create release candidate
git tag -a v2023.8-rc1 -m "Release candidate 1 for 2023.8"
git push origin v2023.8-rc1

# Build and test RC
make dist
# Test in various environments
```

### Final Release Preparation

#### Version Updates
```bash
# Update version files
./scripts/update-version.sh 2023.8

# Files to update:
# - configure.ac
# - rust/Cargo.toml
# - NEWS.md
# - docs/version.md
```

#### Release Notes
```markdown
# NEWS.md
## [2023.8] - 2023-08-01

### Added
- New feature A
- New feature B

### Changed
- Improved performance of X
- Updated dependency Y

### Fixed
- Bug fix 1
- Bug fix 2

### Security
- Security fix 1
- Security fix 2
```

## Build Process

### Release Build Environment

#### Build Requirements
```bash
# Install build dependencies
./ci/installdeps.sh
./ci/install-cxx.sh

# Install release tools
sudo dnf install -y \
    rpm-build \
    rpmdevtools \
    createrepo_c \
    gnupg2
```

#### Build Configuration
```bash
# Configure for release build
./autogen.sh \
    --prefix=/usr \
    --libdir=/usr/lib64 \
    --sysconfdir=/etc \
    --enable-release

# Build with optimizations
make CFLAGS="-O2 -DNDEBUG" CXXFLAGS="-O2 -DNDEBUG"
```

### Package Building

#### RPM Package
```bash
# Create RPM package
make rpm

# Or manually
rpmbuild -ba packaging/rpm-ostree.spec

# Sign package
rpm --addsign rpm-ostree-2023.8-1.fc35.x86_64.rpm
```

#### Source Distribution
```bash
# Create source tarball
make dist

# Sign tarball
gpg --detach-sign --armor rpm-ostree-2023.8.tar.gz
```

### Container Images

#### OCI Image Building
```bash
# Build OCI image
rpm-ostree compose build-ostree \
    --repo=/path/to/repo \
    --output-oci=/path/to/oci-image \
    treefile.yaml

# Push to registry
rpm-ostree oci push \
    --registry=quay.io \
    --repository=coreos/rpm-ostree \
    --tag=2023.8 \
    /path/to/oci-image
```

## Release Publication

### Tagging and Pushing

#### Git Tagging
```bash
# Create annotated tag
git tag -a v2023.8 -m "Release 2023.8"

# Push tag
git push origin v2023.8

# Push release branch
git push origin release-2023.8
```

#### GitHub Release
```bash
# Create GitHub release
gh release create v2023.8 \
    --title "rpm-ostree 2023.8" \
    --notes-file NEWS.md \
    --draft

# Upload assets
gh release upload v2023.8 \
    rpm-ostree-2023.8.tar.gz \
    rpm-ostree-2023.8.tar.gz.asc
```

### Package Distribution

#### RPM Repository
```bash
# Add to repository
cp rpm-ostree-2023.8-1.fc35.x86_64.rpm /path/to/repo/

# Update repository metadata
createrepo_c /path/to/repo/

# Sign repository
gpg --detach-sign --armor /path/to/repo/repodata/repomd.xml
```

#### Container Registry
```bash
# Push to multiple registries
rpm-ostree oci push \
    --registry=quay.io \
    --repository=coreos/rpm-ostree \
    --tag=2023.8 \
    /path/to/oci-image

rpm-ostree oci push \
    --registry=docker.io \
    --repository=coreos/rpm-ostree \
    --tag=2023.8 \
    /path/to/oci-image
```

### Documentation Updates

#### Website Updates
```bash
# Update documentation
make docs

# Deploy to website
./scripts/deploy-docs.sh

# Update API documentation
make api-docs
```

#### Release Announcement
```markdown
# Release announcement template
# rpm-ostree 2023.8 Released

We are pleased to announce the release of rpm-ostree 2023.8.

## Highlights
- Feature A: Description
- Feature B: Description
- Performance improvements
- Bug fixes

## Download
- Source: https://github.com/coreos/rpm-ostree/releases/tag/v2023.8
- RPM: Available in Fedora repositories
- Container: quay.io/coreos/rpm-ostree:2023.8

## Documentation
- User Guide: https://coreos.github.io/rpm-ostree/
- API Reference: https://coreos.github.io/rpm-ostree/api/
- Migration Guide: https://coreos.github.io/rpm-ostree/migration/
```

## Post-release Activities

### Monitoring

#### Release Health
```bash
# Monitor release downloads
# Track GitHub release statistics
# Monitor package installation rates
# Check for reported issues
```

#### Issue Tracking
```bash
# Monitor GitHub issues
# Track bug reports
# Monitor user feedback
# Address critical issues
```

### Maintenance

#### Patch Releases
```bash
# Create patch branch
git checkout -b release-2023.8.1

# Apply fixes
git cherry-pick <fix-commit>

# Update version
./scripts/update-version.sh 2023.8.1

# Create patch release
git tag -a v2023.8.1 -m "Release 2023.8.1"
git push origin v2023.8.1
```

#### Security Updates
```bash
# Security patch process
# 1. Identify security issue
# 2. Create security branch
# 3. Apply fix
# 4. Test thoroughly
# 5. Release security update
# 6. Notify users
```

## Release Automation

### CI/CD Pipeline

#### GitHub Actions
```yaml
# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build
        run: |
          ./ci/installdeps.sh
          ./autogen.sh
          make
      - name: Test
        run: make check
      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body: |
            Release ${{ github.ref }}
            See NEWS.md for details
          draft: false
          prerelease: false
```

#### Automated Testing
```yaml
# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install dependencies
        run: ./ci/installdeps.sh
      - name: Build
        run: |
          ./autogen.sh
          make
      - name: Test
        run: make check
      - name: Integration test
        run: make check-integration
```

### Release Scripts

#### Version Update Script
```bash
#!/bin/bash
# scripts/update-version.sh

VERSION=$1
if [ -z "$VERSION" ]; then
    echo "Usage: $0 <version>"
    exit 1
fi

# Update configure.ac
sed -i "s/AC_INIT(\[rpm-ostree\], \[.*\])/AC_INIT([rpm-ostree], [$VERSION])/" configure.ac

# Update Cargo.toml
sed -i "s/version = \".*\"/version = \"$VERSION\"/" rust/Cargo.toml

# Update NEWS.md
echo "## [$VERSION] - $(date +%Y-%m-%d)" >> NEWS.md

echo "Version updated to $VERSION"
```

#### Release Script
```bash
#!/bin/bash
# scripts/release.sh

VERSION=$1
if [ -z "$VERSION" ]; then
    echo "Usage: $0 <version>"
    exit 1
fi

# Update version
./scripts/update-version.sh $VERSION

# Build
make distclean
./autogen.sh
make

# Test
make check

# Create tag
git add .
git commit -m "Release $VERSION"
git tag -a v$VERSION -m "Release $VERSION"

# Push
git push origin v$VERSION

echo "Release $VERSION created"
```

## Best Practices

### Release Management
1. **Plan ahead**: Schedule releases well in advance
2. **Test thoroughly**: Ensure quality before release
3. **Document changes**: Maintain clear release notes
4. **Monitor post-release**: Track issues and feedback

### Version Control
1. **Use semantic versioning**: Follow SemVer guidelines
2. **Tag releases**: Create annotated tags
3. **Maintain branches**: Keep release branches for patches
4. **Cherry-pick carefully**: Apply only necessary fixes

### Communication
1. **Announce releases**: Notify users of new releases
2. **Document breaking changes**: Clear migration guides
3. **Provide support**: Help users with issues
4. **Gather feedback**: Listen to user input

---

*Following this release process ensures consistent, reliable, and well-documented releases of rpm-ostree. Proper release management is essential for maintaining user trust and project stability.*