Release Process¶

This document outlines the steps to create and publish a new release for the FastAPI RBAC project. Releases are versioned using Git tags, which automatically trigger a GitHub Actions workflow to build and push Docker images to Docker Hub.

Prerequisites¶

Git: Ensure Git is installed and configured on your local machine.
Docker Hub Account: You need an account on Docker Hub where the images will be pushed.
GitHub Secrets: The following secrets must be configured in the GitHub repository settings under "Secrets and variables" > "Actions":
- DOCKERHUB_USERNAME: Your Docker Hub username.
- DOCKERHUB_TOKEN: A Docker Hub access token with read/write permissions.

Release history SSOT: docs/release-notes.md. There is no root CHANGELOG.md. Docker Hub repository descriptions are updated from backend/README.dockerhub.md, react-frontend/README.dockerhub.md, and backend/README.worker.dockerhub.md via .github/workflows/docker-publish.yml — not from release notes.

Versioning Strategy¶

We use Semantic Versioning for our releases. Tags should follow these patterns:

Stable Releases: vX.Y.Z (e.g., v1.0.0, v1.2.3, v2.0.0)
Pre-releases (e.g., Beta, Alpha, RC): vX.Y.Z-beta.N, vX.Y.Z-alpha.N, vX.Y.Z-rc.N (e.g., v0.1.0-beta.1, v1.0.0-rc.2)

The GitHub Actions workflow is configured to trigger on any tag starting with v.

Steps to Create a Release¶

Update Release Notes:
- Before creating a release, ensure the docs/release-notes.md file (release history SSOT) is updated with the new version information.
- Add a new entry at the top of the version history section with:
- Version number (e.g., v1.0.0 or v0.1.0-beta.1)
- Release date in YYYY-MM-DD format
- Summary of changes categorized as "New Features", "Bug Fixes", and "Breaking Changes"
- Optionally, include "Technical Details" with implementation notes
- You can generate an ephemeral draft of changes from Git history with:
```
git log <previous_tag>..HEAD --pretty=format:"- %s" > changelog.txt
```
- Review and edit the generated list (changelog.txt is gitignored), then add it to docs/release-notes.md under the appropriate categories.
Prepare Your Branch:
- Ensure your main working branch (e.g., main) contains all the code changes, bug fixes, and features intended for this release.
- Pull the latest changes from the remote repository to ensure your local branch is up-to-date:
```
git checkout main  # Or your primary development branch
git pull origin main
```
Create a Git Tag:
- Once your branch is ready and all changes are committed, create a new Git tag with the desired version number.
- For a stable release:
```
git tag v1.0.0
```
- For a pre-release (e.g., a beta):
```
git tag v0.1.0-beta.1
```
- Replace v1.0.0 or v0.1.0-beta.1 with the actual version you are releasing.
Push the Git Tag to GitHub:
- Pushing the tag to the remote repository on GitHub will trigger the release workflow.
```
git push origin v1.0.0  # Replace with your tag name
```
- To push all your local tags (if you've created multiple):
```
git push origin --tags
```

What Happens Next (Automation)¶

GitHub Actions Workflow Triggered: Docker Publish runs when a v* tag is pushed (human/local push), or via workflow_dispatch (Actions → Run workflow, or automatic dispatch from Release Tag on Merge after a Release PR). Tags created with GITHUB_TOKEN inside Actions do not start other workflows on push alone, which is why the Release Tag job dispatches Docker Publish explicitly. The workflow checks out the tagged commit (including on workflow_dispatch).
Prepare: Resolves IMAGE_TAG / metadata and validates Dockerfiles plus Hub README paths before any multi-arch build starts.
Parallel image builds (matrix): Backend, frontend, and worker build in parallel (fail-fast: false so every shard finishes for diagnosis). Each image is pushed to Docker Hub as :${IMAGE_TAG} only (e.g. yourusername/fastapi-rbac-backend:v1.0.0) — not :latest yet.
Promote :latest: Only if all three builds succeed, a promote job retags each image’s :latest from the version tag via docker buildx imagetools create (no rebuild). See docs/adr/0002-docker-publish-job-dag.md.
Hub descriptions: After promote, repository long descriptions are updated from backend/README.dockerhub.md, react-frontend/README.dockerhub.md, and backend/README.worker.dockerhub.md (not from docs/release-notes.md). That job soft-fails so Hub API flake does not fail the release.
Failed runs: The workflow fails if prepare, any build shard, or promote fails. A failed run may leave some :${IMAGE_TAG} tags on Hub; :latest stays on the previous good release until promote succeeds. Re-run overwrites the same version tags.

Verifying the Release¶

Check GitHub Actions:
- Navigate to the "Actions" tab in your GitHub repository.
- You should see the "Docker Publish" workflow running or completed for the tag you pushed.
- Verify that Prepare, all three Build matrix jobs, and Promote latest have succeeded. Hub descriptions may soft-fail without invalidating the image release.
Check Docker Hub:
- Log in to your Docker Hub account.
- Navigate to your repositories (e.g., fastapi-rbac-backend, fastapi-rbac-frontend, fastapi-rbac-worker).
- You should see the new image tags corresponding to the Git tag you pushed (e.g., v1.0.0, v0.1.0-beta.1).

Example: Releasing `v0.2.0`¶

Using the Release Automation Script (Recommended)¶

We have automation scripts that simplify the release process by handling all the steps in one command:

For PowerShell users:

cd scripts\deployment\release
.\Create-Release.ps1 -Version v0.2.0

For Bash users:

cd scripts/deployment/release
./create-release.sh -v v0.2.0

These scripts will:

Generate a changelog from Git history
Update root VERSION (without the leading v) and docs/release-notes.md
Commit those files with docs: update release notes and version for <tag>
Create and push the Git tag (refuses if the tag already exists on remote; no force-push)
Optionally build and push Docker images

You can use the -DryRun (PowerShell) or --dry-run (Bash) flag to simulate the release process without making any actual changes:

.\Create-Release.ps1 -Version v0.2.0 -DryRun

./create-release.sh -v v0.2.0 --dry-run

Dry-run behavior (both scripts):

Skips git pull origin main (non-mutating simulation)
Does not write VERSION or docs/release-notes.md, commit, tag, or push
Still generates temporary changelog.txt and leaves it in place (same as a successful dry-run cleanup message: “Would clean up”)
Still prompts for interactive confirmations when warnings apply

For more options, run the scripts with the -Help or --help flag.

Manual Release Process¶

If you prefer to release manually, follow these steps:

Ensure main branch is ready.

git checkout main
git pull origin main
# (Make sure all commits for v0.2.0 are on main)

Create the tag:
```
git tag v0.2.0
```
Push the tag:
```
git push origin v0.2.0
```
Monitor GitHub Actions and verify images on Docker Hub.

By following these steps, you can consistently create and publish new versions of the application.