Versioning and Releases

This project uses Semantic Release to automate version management and package publishing.

Overview

We follow Semantic Versioning (SemVer) vMajor.Minor.Patch. The version number is automatically determined based on the commit messages in the release.

Commit Message Convention

We use Conventional Commits to structure commit messages. This is mandatory for the automated release process to work correctly.

• fix: patches a bug (corresponds to PATCH in SemVer).
• feat: introduces a new feature (corresponds to MINOR in SemVer).
• BREAKING CHANGE: (in the footer or with !) introduces a breaking API change (corresponds to MAJOR in SemVer).
• Other types like chore:, docs:, style:, refactor:, perf:, test: do not trigger a release but are good for organization.

Example:

feat(auth): add google oauth login

Workflows

1. Pull Request Validation (pr.yml)

• Trigger: Open, edit, or synchronize a Pull Request targeting main.
• Actions:
  • Validates the PR title matches Conventional Commits.
  • Runs tests, linting, and type checking.
  • Runs Semantic Release in Dry-Run Mode. This calculates the next potential version based on the commits but does not publish it.
  • Useful for verifying that your changes will trigger the expected version bump.

2. Release and Deploy (deploy.yml)

• Trigger: Merge a Pull Request into main.
• Actions:
  • Semantic Release:
    • Analyzes new commits.
    • Generates a new version number.
    • Creates a Git tag (e.g., v1.2.3).
    • Generates release notes in GitHub Releases.
    • Note: CHANGELOG.md is not updated in the repository to avoid triggering branch protection rules. Release notes are available on the GitHub Releases page.
  • Deployment:
    • Builds the Docker image with the new version tag.
    • Pushes to AWS ECR.
    • Deploys infrastructure using OpenTofu.
    • Runs database migrations.

Configuration

• Workflow Files:
  • .github/workflows/pr.yml
  • .github/workflows/deploy.yml
• Semantic Release Config: Configured via cycjimmy/semantic-release-action inputs in the workflow files and potentially .releaserc.json (if present).

Manual Releases

Releases are fully automated. To trigger a release, simply merge a PR with a valid commit message (feat, fix, etc.) into main.