website-and-documentation/doc/RELEASE.md

Release Process

This document describes the release process for the IPCEI-CIS Developer Framework.

Overview

The project uses Semantic Versioning (SemVer) for releases. Each release is triggered by a Git tag and automatically creates:

• Multi-platform Docker images (linux/amd64, linux/arm64)
• Forgejo release with release notes
• Automatically generated changelog

Versioning Schema

We follow Semantic Versioning 2.0.0:

• MAJOR.MINOR.PATCH (e.g., v1.2.3)
• MAJOR: Breaking changes (incompatible API changes)
• MINOR: New features (backwards compatible)
• PATCH: Bug fixes (backwards compatible)

Creating a Release

1. Check Prerequisites

Ensure that:

• All tests are passing (task test)
• CI pipeline runs successfully
• All desired changes are in the main branch
• You have the latest version: git pull origin main

2. Determine Version

Determine the new version number based on the changes:

# Show current tag
git describe --tags --abbrev=0

# Show commits since last release
git log $(git describe --tags --abbrev=0)..HEAD --oneline

3. Create Tag

Create an annotated tag with the new version:

# For a new patch release (e.g., v1.2.3 → v1.2.4)
git tag -a v1.2.4 -m "Release v1.2.4"

# For a minor release (e.g., v1.2.3 → v1.3.0)
git tag -a v1.3.0 -m "Release v1.3.0"

# For a major release (e.g., v1.2.3 → v2.0.0)
git tag -a v2.0.0 -m "Release v2.0.0"

4. Push Tag

Push the tag to the repository - this triggers the release pipeline:

git push origin v1.2.4

5. Monitor Release Pipeline

The release pipeline (release.yaml) starts automatically:

1. Open the Actions tab in Forgejo
2. Monitor the release workflow
3. On success: Release is visible on the Releases page

What Happens Automatically?

The release pipeline (release.yaml) performs the following steps:

1. Build Docker Images

   • Multi-platform build (AMD64 + ARM64)
   • Images are tagged with:
     • vX.Y.Z (exact version, e.g., v1.2.3)
     • vX.Y (minor version, e.g., v1.2)
     • vX (major version, e.g., v1)
     • latest (latest release)

2. Push Images

   • To the container registry (Forgejo Packages)

3. Generate Changelog

   • Automatically from Git commits since last release
   • Format: - Commit Message (hash)

4. Create Forgejo Release

   • With generated release notes
   • Contains build versions (Node, Go, Hugo)
   • Docker pull commands
   • Changelog

Using Docker Images

After a successful release, the images are available:

# Specific version
docker pull <registry>/<repository>:v1.2.3

# Latest
docker pull <registry>/<repository>:latest

# Major/Minor version
docker pull <registry>/<repository>:v1
docker pull <registry>/<repository>:v1.2

Best Practices

Commit Messages

Use meaningful commit messages, as they will appear in the changelog:

# Good
git commit -m "fix: correct multi-platform Docker build for ARM64"
git commit -m "feat: add automatic release pipeline"
git commit -m "docs: update RELEASE.md"

# Bad
git commit -m "fix stuff"
git commit -m "wip"

Conventional Commits help with categorization:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation
• chore: - Maintenance
• refactor: - Code restructuring
• test: - Tests

Release Frequency

• Patch releases: As needed (bug fixes)
• Minor releases: Regular (new features)
• Major releases: Rare (breaking changes)

Hotfixes

For urgent bug fixes:

1. Create branch from last release tag
2. Fix the bug
3. Create new patch release

git checkout v1.2.3
git checkout -b hotfix/critical-bug
# Implement fix
git commit -m "fix: critical bugfix"
git tag -a v1.2.4 -m "Release v1.2.4 - Hotfix"
git push origin v1.2.4

Troubleshooting

Release Pipeline Fails

1. Check Secrets: PACKAGES_USER, PACKAGES_TOKEN must be set

2. Check Logs: Open the failed workflow in the Actions tab

3. Local Test:

   task build:oci-image
   task test:oci-image
   

Delete/Correct Tag

Locally:

git tag -d v1.2.3

Remote:

git push --delete origin v1.2.3

⚠️ Warning: Releases should not be deleted after they have been published!

Edit Release Notes Afterwards

Release notes can be manually edited in Forgejo:

1. Go to Releases
2. Click on the release
3. Click "Edit"

Further Information

• Semantic Versioning
• Conventional Commits
• Keep a Changelog