Skip to content

Latest commit

 

History

History
108 lines (74 loc) · 5 KB

management.md

File metadata and controls

108 lines (74 loc) · 5 KB

Release Management

This document outlines the standards and best practices for release management across all Bayat projects, following a Trunk-Based Development model.

Versioning Scheme

Semantic Versioning (SemVer)

All Bayat projects must follow semantic versioning guidelines in the format of MAJOR.MINOR.PATCH:

  • MAJOR: Incompatible API changes.
  • MINOR: Backwards-compatible functionality additions.
  • PATCH: Backwards-compatible bug fixes.

Examples:

  • v1.0.0 - Initial stable release
  • v1.1.0 - New features added
  • v1.1.1 - Bug fixes

Pre-release identifiers (-alpha, -beta, -rc) can be used for builds from feature branches if needed for early testing, but they are not part of the formal release process from main.

Release Philosophy

In Trunk-Based Development, the main branch is always in a releasable state. The release process is lightweight and highly automated.

  • Release from main: All releases are cut directly from the main branch.
  • Tags as Releases: A release is defined by a Git tag on a specific commit in the main branch.
  • Continuous Deployment: The goal is to be able to release at any time. Deployments to production are automated and triggered by the creation of a release tag.
  • Decoupled Deployment and Release: Features may be deployed to production but hidden behind feature flags. The "release" of a feature is the act of enabling its feature flag, which is independent of the deployment schedule.

Release Process

Pre-Release Checklist

Before tagging a commit for release, ensure the following:

  • The commit on main has passed all CI checks (build, tests, static analysis, security scans).
  • The commit has been deployed to and verified in a staging environment.
  • Release notes, based on conventional commits, have been automatically generated and reviewed.
  • Any necessary documentation updates have been merged.

Creating a Release

  1. Identify the Release Commit: Choose the commit on main that will be released.
  2. Tag the Commit: Create a new Git tag with the appropriate semantic version. 
    # Ensure you are on the latest main branch
git checkout main
git pull

# Tag the latest commit
git tag -a v1.2.3 -m "Release version 1.2.3"

# Push the tag to the remote repository
git push origin v1.2.3
  3. Automated Deployment: Pushing the tag will trigger the CI/CD pipeline to build the release artifacts and deploy them to production.

Release Notes

Release notes should be automatically generated from conventional commit messages since the last release tag. This process should be part of the CI/CD pipeline. The notes must include:

  • Version number and release date.
  • A summary of changes, categorized by type (Features, Bug Fixes, etc.).
  • Details on any breaking changes, with a clear migration guide.
  • A list of contributors.

Deployment Strategies

While the release itself is a single point in time (the tag), the deployment of the code can use various strategies to minimize risk:

  • Canary Deployments: The new version is rolled out to a small subset of users/servers first.
  • Blue-Green Deployments: The new version is deployed to a parallel production environment, and traffic is switched over once it's verified.
  • Progressive Rollout with Feature Flags: Features are deployed in a disabled state and then gradually enabled for different user segments.

Hotfixes

Hotfixes follow the same process as any other bug fix. There is no separate "hotfix" workflow.

  1. A bugfix/* branch is created from main.
  2. The fix is developed and tested.
  3. A PR is created, reviewed (expedited if necessary), and merged into main.
  4. A new patch release is tagged on main (e.g., v1.2.3 -> v1.2.4) and deployed.

Rollback Procedures

Rollbacks should be rare, but a clear process is necessary.

  • Rollback Trigger: A rollback is initiated if a release causes a critical issue in production (e.g., major outage, data corruption).
  • Rollback Method: The primary method for rollback is to deploy the previously tagged stable version.
  • Fix-Forward: Whenever possible, a "fix-forward" approach is preferred. This means quickly developing, testing, and deploying a new patch release that fixes the issue, rather than rolling back. This is often faster and safer in a continuous deployment environment.

Communication

  • Release Announcements: Automated notifications should be sent to relevant stakeholders (e.g., in a Slack channel) when a new version is deployed to production.
  • Changelog: The CHANGELOG.md file in the repository should be automatically updated with each release.
  • Deprecation Notices: Any deprecations should be announced in the release notes well in advance of the removal of the feature.