Release Management

First PublishedFeb 17, 2026ByAtif Alam

Release management is the process of versioning, tagging, documenting, and publishing your software. Good release management makes deployments predictable, rollbacks traceable, and changelogs automatic.

Semantic Versioning (SemVer)

The most widely adopted versioning scheme:

1
MAJOR.MINOR.PATCH
2
  │     │     │
3
  │     │     └── Bug fixes (backward compatible)
4
  │     └──────── New features (backward compatible)
5
  └────────────── Breaking changes (not backward compatible)
6

7
Examples:
8
  1.0.0  →  Initial release
9
  1.1.0  →  Added a new feature
10
  1.1.1  →  Fixed a bug
11
  2.0.0  →  Breaking API change

Change Type	Version Bump	Example
Bug fix, patch	`1.2.3` → `1.2.4`	Fix login timeout
New feature (backward compatible)	`1.2.3` → `1.3.0`	Add search endpoint
Breaking change	`1.2.3` → `2.0.0`	Remove deprecated API

Pre-Release Versions

1
2.0.0-alpha.1     First alpha
2
2.0.0-beta.1      First beta
3
2.0.0-rc.1        Release candidate
4
2.0.0             Stable release

SemVer Rules

Patch version MUST be incremented for backward-compatible bug fixes.
Minor version MUST be incremented for backward-compatible new functionality.
Major version MUST be incremented for any backward-incompatible changes.
Once a version is released, its contents MUST NOT be modified — release a new version instead.

Conventional Commits and SemVer

Conventional Commits provide a structured commit message format that automation tools can parse to determine the version bump:

1
feat: add user search endpoint          → minor bump (1.2.0 → 1.3.0)
2
fix: correct login timeout handling     → patch bump (1.2.0 → 1.2.1)
3
feat!: redesign authentication API      → major bump (1.2.0 → 2.0.0)
4

5
Format:
6
  <type>(<scope>): <description>
7

8
  [optional body]
9

10
  [optional footer(s)]
11
  BREAKING CHANGE: <description>

Commit Type	SemVer Bump
`fix:`	Patch
`feat:`	Minor
`feat!:` or `BREAKING CHANGE:` footer	Major
`docs:`, `chore:`, `style:`, `refactor:`, `test:`	No bump (or patch, configurable)

Automated Release Tools

semantic-release

semantic-release fully automates versioning, changelog, and publishing based on commit messages:

1
Commits since last release:
2
  feat: add search API
3
  fix: handle null response
4
  docs: update README
5

6
semantic-release determines:
7
  → Minor bump (feat present)
8
  → 1.3.0 → 1.4.0
9
  → Generates CHANGELOG entry
10
  → Creates Git tag v1.4.0
11
  → Creates GitHub release
12
  → Publishes to npm (if configured)

Setup

1
npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git

1
{
2
  "branches": ["main"],
3
  "plugins": [
4
    "@semantic-release/commit-analyzer",
5
    "@semantic-release/release-notes-generator",
6
    "@semantic-release/changelog",
7
    "@semantic-release/npm",
8
    "@semantic-release/github",
9
    ["@semantic-release/git", {
10
      "assets": ["CHANGELOG.md", "package.json"],
11
      "message": "chore(release): ${nextRelease.version} [skip ci]"
12
    }]
13
  ]
14
}

GitHub Actions

1
name: Release
2
on:
3
  push:
4
    branches: [main]
5

6
permissions:
7
  contents: write
8
  issues: write
9
  pull-requests: write
10

11
jobs:
12
  release:
13
    runs-on: ubuntu-latest
14
    steps:
15
      - uses: actions/checkout@v4
16
        with:
17
          fetch-depth: 0
18
          persist-credentials: false
19
      - uses: actions/setup-node@v4
20
        with:
21
          node-version: 20
22
      - run: npm ci
23
      - run: npx semantic-release
24
        env:
25
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
26
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

release-please (Google)

release-please creates a release PR that accumulates changes. When merged, it creates the tag and GitHub release:

1
Commits accumulate on main:
2
  feat: add search
3
  fix: handle null
4

5
release-please opens a PR:
6
  "chore: release 1.4.0"
7
  - Updates CHANGELOG.md
8
  - Bumps version in package.json
9

10
When you merge the PR:
11
  → Git tag v1.4.0 created
12
  → GitHub release created

GitHub Actions

1
name: Release
2
on:
3
  push:
4
    branches: [main]
5

6
permissions:
7
  contents: write
8
  pull-requests: write
9

10
jobs:
11
  release-please:
12
    runs-on: ubuntu-latest
13
    outputs:
14
      release_created: ${{ steps.release.outputs.release_created }}
15
      tag_name: ${{ steps.release.outputs.tag_name }}
16
    steps:
17
      - uses: googleapis/release-please-action@v4
18
        id: release
19
        with:
20
          release-type: node
21

22
  publish:
23
    needs: release-please
24
    if: ${{ needs.release-please.outputs.release_created }}
25
    runs-on: ubuntu-latest
26
    steps:
27
      - uses: actions/checkout@v4
28
      - uses: actions/setup-node@v4
29
        with:
30
          node-version: 20
31
          registry-url: https://registry.npmjs.org
32
      - run: npm ci
33
      - run: npm publish
34
        env:
35
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Changesets

Changesets is popular in monorepos — developers add changeset files with their PRs:

1
# Developer runs this when making a change
2
npx changeset add
3
# Prompts: What packages changed? Major/minor/patch? Description?
4
# Creates .changeset/funny-llamas-swim.md

1
---
2
"@myorg/api": minor
3
"@myorg/shared": patch
4
---
5

6
Add user search endpoint to the API.

When ready to release, a bot PR accumulates changesets and bumps versions.

Tool Comparison

Feature	semantic-release	release-please	Changesets
Version source	Commit messages	Commit messages	Changeset files
Human review	No (fully automatic)	Yes (release PR)	Yes (changeset PR)
Monorepo	Via plugins	Yes (manifest mode)	Yes (native)
Changelog	Auto-generated	Auto-generated	Auto-generated
Publish	npm, GitHub, Docker, etc.	GitHub release (publish separately)	npm (native)
Best for	Libraries, single packages	Any project wanting review step	Monorepos

Git Tagging

Tags mark specific commits as releases:

1
# Annotated tag (recommended for releases)
2
git tag -a v1.4.0 -m "Release 1.4.0: add search API, fix login timeout"
3
git push origin v1.4.0
4

5
# List tags
6
git tag -l "v1.*"
7

8
# Delete a tag
9
git tag -d v1.4.0
10
git push origin --delete v1.4.0

Tagging Conventions

Convention	Example	Use Case
`v` prefix	`v1.4.0`	Most common for application releases
No prefix	`1.4.0`	Some package managers prefer this
Package scoped	`@myorg/api@1.4.0`	Monorepo per-package tags
Date-based	`2026.02.17`	CalVer (calendar versioning)

Triggering Pipelines on Tags

1
# GitHub Actions — run on version tags
2
on:
3
  push:
4
    tags:
5
      - 'v*'                           # v1.0.0, v2.1.3, etc.
6

7
# GitLab CI
8
release:
9
  rules:
10
    - if: $CI_COMMIT_TAG =~ /^v\d+/

Changelogs

Auto-Generated Changelog

Most release tools generate changelogs from commit messages:

1
# Changelog
2

3
## [1.4.0] - 2026-02-17
4

5
### Features
6
- Add user search endpoint (#123)
7
- Support pagination in list API (#125)
8

9
### Bug Fixes
10
- Fix login timeout handling (#128)
11
- Correct null response in profile API (#130)
12

13
## [1.3.0] - 2026-02-10
14
...

Keep a Changelog Format

The Keep a Changelog convention uses these categories:

Category	What Goes Here
Added	New features
Changed	Changes to existing functionality
Deprecated	Features that will be removed
Removed	Features that were removed
Fixed	Bug fixes
Security	Vulnerability fixes

GitHub and GitLab Releases

GitHub Releases

1
# Create a release via CLI
2
gh release create v1.4.0 \
3
  --title "v1.4.0" \
4
  --notes "## What's Changed
5
- Add search API (#123)
6
- Fix login timeout (#128)" \
7
  --target main
8

9
# Upload release assets
10
gh release upload v1.4.0 ./dist/myapp-linux-amd64 ./dist/myapp-darwin-amd64
11

12
# Auto-generate release notes from PRs
13
gh release create v1.4.0 --generate-notes

GitHub can auto-generate release notes from merged PRs — grouped by labels.

GitLab Releases

1
release:
2
  stage: deploy
3
  image: registry.gitlab.com/gitlab-org/release-cli:latest
4
  rules:
5
    - if: $CI_COMMIT_TAG =~ /^v\d+/
6
  script:
7
    - echo "Creating release for $CI_COMMIT_TAG"
8
  release:
9
    tag_name: $CI_COMMIT_TAG
10
    name: "Release $CI_COMMIT_TAG"
11
    description: ./CHANGELOG.md
12
    assets:
13
      links:
14
        - name: Linux Binary
15
          url: https://example.com/myapp-linux-amd64

Package Publishing

npm

1
publish-npm:
2
  runs-on: ubuntu-latest
3
  steps:
4
    - uses: actions/checkout@v4
5
    - uses: actions/setup-node@v4
6
      with:
7
        node-version: 20
8
        registry-url: https://registry.npmjs.org
9
    - run: npm ci
10
    - run: npm publish
11
      env:
12
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

PyPI

1
publish-pypi:
2
  runs-on: ubuntu-latest
3
  permissions:
4
    id-token: write                     # OIDC (Trusted Publishers)
5
  steps:
6
    - uses: actions/checkout@v4
7
    - uses: actions/setup-python@v5
8
      with:
9
        python-version: "3.12"
10
    - run: pip install build
11
    - run: python -m build
12
    - uses: pypa/gh-action-pypi-publish@release/v1
13
      # Uses OIDC — no API token needed (Trusted Publisher configured on PyPI)

Docker Images

1
publish-docker:
2
  runs-on: ubuntu-latest
3
  steps:
4
    - uses: actions/checkout@v4
5
    - uses: docker/login-action@v3
6
      with:
7
        registry: ghcr.io
8
        username: ${{ github.actor }}
9
        password: ${{ secrets.GITHUB_TOKEN }}
10
    - uses: docker/build-push-action@v6
11
      with:
12
        push: true
13
        tags: |
14
          ghcr.io/${{ github.repository }}:${{ github.ref_name }}
15
          ghcr.io/${{ github.repository }}:latest

Release Strategies

Continuous Release (Every Merge to Main)

1
main: commit ──► CI ──► tag v1.4.0 ──► publish
2
      commit ──► CI ──► tag v1.4.1 ──► publish

Best for libraries, APIs, SaaS. Every merge to main is a potential release.

Scheduled Release (Release Train)

1
main: commit ──► commit ──► commit ──► Release cut (every 2 weeks)
2
                                            ──► tag v1.4.0 ──► publish

Best for products with coordinated releases, QA cycles, or marketing announcements.

Release Branches

1
main ────────●──────●──────●──────●──────●───►
2
              \                    \
3
               ▼                    ▼
4
         release/1.4 ──● ──●     release/1.5 ──●
5
              (hotfixes)              (hotfixes)

Best for software that maintains multiple versions simultaneously (e.g. open-source libraries).

Calendar Versioning (CalVer)

Some projects use date-based versioning instead of SemVer:

1
2026.02.17     (YYYY.MM.DD)
2
2026.2.1       (YYYY.M.micro)
3
26.2           (YY.M)

Project	CalVer Format
Ubuntu	`YY.MM` (e.g. 24.04)
pip	`YY.N` (e.g. 24.0)
Terraform	`MAJOR.MINOR.PATCH` (SemVer, but frequent)
Docker Desktop	`MAJOR.MINOR.PATCH` (SemVer)

CalVer works well for projects where compatibility is less relevant than recency (e.g. operating systems, infrastructure tools).

Key Takeaways

Semantic Versioning (MAJOR.MINOR.PATCH) communicates the impact of changes to consumers.
Conventional Commits enable automated version bumps — feat: = minor, fix: = patch, feat!: = major.
semantic-release is fully automatic; release-please adds a review step via PR; Changesets is best for monorepos.
Git tags mark release points — trigger pipelines with tag-based triggers (v*).
Changelogs should be auto-generated from commits or PRs — not hand-written.
GitHub/GitLab releases combine a tag with release notes and downloadable assets.
Choose a release strategy: continuous (every merge), scheduled (release train), or branched (multiple versions).