website-and-documentation/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](https://semver.org/):

- `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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
# 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

```bash
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**:

   ```bash
   task build:oci-image
   task test:oci-image
   ```

### Delete/Correct Tag

**Locally:**

```bash
git tag -d v1.2.3
```

**Remote:**

```bash
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](https://semver.org/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Keep a Changelog](https://keepachangelog.com/)