Skip to main content

Release Guide

This document outlines a language- and framework-agnostic process for creating a release version of any project — whether it's a Python package, backend app, frontend app, or any other software. It uses Conventional Commits and Semantic Versioning for consistency and automation.

1. Prepare for Release​

Ensure all features and fixes are merged into main​

  • Complete and test all features on feature branches.
  • Merge into the main (or master) branch using Pull Requests (PRs).
  • Use Conventional Commits for all commit messages.

Example commit types:

  • feat: New features
  • fix: Bug fixes
  • chore: Maintenance tasks
  • refactor: Code improvements without changing behavior

2. Run Tests and Code Quality Checks​

Automated CI/CD pipelines should handle:

  • Unit and integration tests
  • Linting and static analysis
  • Security or policy checks

Ensure all pipelines pass before proceeding with a release.

3. Versioning Strategy​

We use Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

Release cadence:

  • MAJOR: Breaking changes – released monthly.
  • MINOR: New features – released every Friday.
  • PATCH: Bug fixes – released as needed.

The versioning should be updated automatically by CI/CD tools or manually by editing the designated version source (e.g., VERSION file, project metadata).

4. Tag the Release in Git​

The release should be tagged in version control using the format vX.Y.Z. This can be handled by automation or done manually.

Ensure the tag is pushed and referenced in release notes.

5. Create Release Notes​

Generate release notes based on Conventional Commits:

  • Summarize added features, fixes, and changes.
  • Categorize by type (Features, Fixes, Chores, etc.).
  • Link to related issues or pull requests.

CI/CD pipelines may auto-generate these or require manual entry in the version control platform (e.g., GitHub, GitLab).

6. Distribute the Release​

Depending on the project type, releases may be published to:

  • Package registries (e.g., PyPI, npm)
  • Cloud platforms or app stores
  • Static hosting providers
  • Container registries

Your CI/CD system should be configured to handle distribution automatically.

Summary Checklist​

  • Merge all code to main
  • Ensure Conventional Commits are used
  • CI/CD pipelines pass
  • Update version according to schedule
  • Tag the release
  • Generate and publish release notes
  • Distribute or publish release

References​