Skip to main content

Release Management

Versioning (Semantic Versioning)​

The project follows Semantic Versioning (SemVer) with the format MAJOR.MINOR.PATCH:

  • MAJOR version (x.0.0): When you make incompatible API changes
  • MINOR version (0.x.0): When you add functionality in a backward-compatible manner
  • PATCH version (0.0.x): When you make backward-compatible bug fixes

Pre-Release Checklist​

Before releasing a new version, ensure you have completed the following:

  • All changes are committed and pushed to the vMAJOR.MINOR.x branch.
  • The version number is updated in package.json (use scripts/update-version.sh to synchronise it across files).
  • All tests pass (in devel mode, local, docker and podman).
  • Start a Docker container with pnpm docker-up and run scripts/compare-versions.sh to verify version consistency between development environment and Docker container (requires Docker container to be running). This script compares SQLite versions by major version only (e.g., 3.45.1 vs 3.51.1 are considered compatible), and compares Node, npm, and Duplistatus versions exactly.
  • Documentation is up to date, update the screenshots (use pnpm take-screenshots)
  • Release notes are prepared in documentation/docs/release-notes/VERSION.md.
  • Run scripts/generate-readme-from-intro.sh to update README.md with the new version and any changes from documentation/docs/intro.md. This script also automatically generates README_dockerhub.md and RELEASE_NOTES_github_VERSION.md.

Release Process Overview​

The recommended release process uses GitHub Pull Requests and Releases (see below). This provides better visibility, review capabilities, and automatically triggers Docker image builds. The command-line method is available as an alternative.

This is the preferred method as it provides better traceability and automatically triggers Docker builds.

Step 1: Create Pull Request​

  1. Navigate to the duplistatus repository on GitHub.
  2. Click the "Pull requests" tab.
  3. Click "New pull request."
  4. Set the base branch to master and the compare branch to vMAJOR.MINOR.x.
  5. Review the changes preview to ensure everything looks correct.
  6. Click "Create pull request."
  7. Add a descriptive title (e.g., "Release v1.2.0") and description summarizing the changes.
  8. Click "Create pull request" again.

Step 2: Merge the Pull Request​

After reviewing the pull request:

  1. If there are no conflicts, click the green "Merge pull request" button.
  2. Choose your merge strategy (typically "Create a merge commit").
  3. Confirm the merge.

Step 3: Create GitHub Release​

Once the merge is complete, create a GitHub release:

  1. Navigate to the duplistatus repository on GitHub.
  2. Go to the "Releases" section (or click "Releases" in the right sidebar).
  3. Click "Draft a new release."
  4. In the "Choose a tag" field, type your new version number in the format vMAJOR.MINOR.PATCH (e.g., v1.2.0). This will create a new tag.
  5. Select master as the target branch.
  6. Add a release title (e.g., "Release v1.2.0").
  7. Add a description documenting the changes in this version. You can:
    • Copy the contents from RELEASE_NOTES_github_VERSION.md (generated by scripts/generate-readme-from-intro.sh)
    • Or reference release notes from documentation/docs/release-notes/ (but note that relative links won't work in GitHub releases)
  8. Click "Publish release."

What happens automatically:

  • A new Git tag is created
  • The "Build and Publish Docker Image" workflow is triggered
  • Docker images are built for AMD64 and ARM64 architectures
  • Images are pushed to:
    • Docker Hub: wsjbr/duplistatus:VERSION and wsjbr/duplistatus:latest (if this is the latest release)
    • GitHub Container Registry: ghcr.io/wsj-br/duplistatus:VERSION and ghcr.io/wsj-br/duplistatus:latest (if this is the latest release)

Method 2: Command Line (Alternative)​

If you prefer using the command line, follow these steps:

Step 1: Update Local Master Branch​

Ensure your local master branch is up to date:

# Checkout the master branch
git checkout master

# Pull the latest changes from the remote repository
git pull origin master

Step 2: Merge Development Branch​

Merge the vMAJOR.MINOR.x branch into master:

# Merge the vMAJOR.MINOR.x branch into master
git merge vMAJOR.MINOR.x

If there are merge conflicts, resolve them manually:

  1. Edit the conflicted files
  2. Stage the resolved files: git add <file>
  3. Complete the merge: git commit

Step 3: Tag the Release​

Create an annotated tag for the new version:

# Create an annotated tag for the new version
git tag -a vMAJOR.MINOR.PATCH -m "Release vMAJOR.MINOR.PATCH - Brief description"

The -a flag creates an annotated tag (recommended for releases), and the -m flag adds a message.

Step 4: Push to GitHub​

Push both the updated master branch and the new tag:

# Push the updated master branch
git push origin master

# Push the new tag
git push origin vMAJOR.MINOR.PATCH

Alternatively, push all tags at once: git push --tags

Step 5: Create GitHub Release​

After pushing the tag, create a GitHub release (see Method 1, Step 3) to trigger the Docker build workflow.

Manual Docker Image Build​

To manually trigger the Docker image build workflow without creating a release:

  1. Navigate to the duplistatus repository on GitHub.
  2. Click on the "Actions" tab.
  3. Select the "Build and Publish Docker Image" workflow.
  4. Click "Run workflow".
  5. Select the branch to build from (typically master).
  6. Click "Run workflow" again.

Note: Manual builds will not automatically tag images as latest unless the workflow determines it's the latest release.

Releasing Documentation​

The documentation is hosted on GitHub Pages and is deployed separately from the application release. Follow these steps to release updated documentation:

Prerequisites​

  1. Ensure you have a GitHub Personal Access Token with the repo scope.
  2. Set up Git credentials (one-time setup):
cd documentation
./setup-git-credentials.sh

This will prompt you for your GitHub Personal Access Token and store it securely.

Deploy Documentation​

  1. Navigate to the documentation directory:
cd documentation

  1. Ensure all documentation changes are committed and pushed to the repository.

  2. Build and deploy the documentation:

pnpm run deploy

This command will:

When to Deploy Documentation​

Deploy documentation updates:

  • After merging documentation changes to master
  • When releasing a new version (if documentation was updated)
  • After significant documentation improvements

Note: The documentation deployment is independent of application releases. You can deploy documentation multiple times between application releases.

Preparing Release Notes for GitHub​

The generate-readme-from-intro.sh script automatically generates GitHub release notes when run. It reads the release notes from documentation/docs/release-notes/VERSION.md (where VERSION is extracted from package.json) and creates RELEASE_NOTES_github_VERSION.md in the project root.

Example:

# This will generate README.md, README_dockerhub.md, and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

The generated release notes file can be copied and pasted directly into the GitHub release description. All links and images will work correctly in the GitHub release context.

Note: The generated file is temporary and can be deleted after creating the GitHub release. It's recommended to add RELEASE_NOTES_github_*.md to .gitignore if you don't want to commit these files.

Update README.md​

If you've made changes to documentation/docs/intro.md, regenerate the repository README.md:

./scripts/generate-readme-from-intro.sh

This script:

  • Extracts the version from package.json
  • Generates README.md from documentation/docs/intro.md (converts Docusaurus admonitions to GitHub-style alerts, converts links and images)
  • Creates README_dockerhub.md for Docker Hub (with Docker Hub-compatible formatting)
  • Generates RELEASE_NOTES_github_VERSION.md from documentation/docs/release-notes/VERSION.md (converts links and images to absolute URLs)
  • Updates the table of contents using doctoc

Commit and push the updated README.md along with your release.