particle-os-tools/docs/apt-layer/rpm-ostree/contributing/release.md

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 (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

# 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

# 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

# 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

# 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

# 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

# Update version files
./scripts/update-version.sh 2023.8

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

Release Notes

# 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

# 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

# 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

# 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

# Create source tarball
make dist

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

Container Images

OCI Image Building

# 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

# 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

# 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

# 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

# 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

# Update documentation
make docs

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

# Update API documentation
make api-docs

Release Announcement

# 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

# Monitor release downloads
# Track GitHub release statistics
# Monitor package installation rates
# Check for reported issues

Issue Tracking

# Monitor GitHub issues
# Track bug reports
# Monitor user feedback
# Address critical issues

Maintenance

Patch Releases

# 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

# 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

# .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

# .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

#!/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

#!/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.