EMZETT.
Login

Emzett Wiki

Git tags, releases and changelog: Publishing versions cleanly

Properties1
tagsglossar, git, release

2 min read

Git tags, releases and changelog: Publishing versions cleanly

In short: Tags mark certain commits as a version, releases bundle them with explanations and files, and a changelog describes for users what has changed.

In more detail: A software version is a uniquely named state of the code. For this you use Git tags, version numbers (SemVer) and release notes.

In Depth

Tags

git tag v1.4.0                       # lightweight tag
git tag -a v1.4.0 -m "Version 1.4.0" # annotated tag (with author, date, message)
git push origin v1.4.0               # publish tag (tags are not pushed automatically)
git tag -l 'v1.*'                    # list tags
git checkout v1.4.0                  # look at this state
git tag -d v1.4.0                    # delete locally

Tags are immutable markers (do not move them once published). For releases use annotated (and possibly signed, -s) tags.

Version numbers

Semantic versioning: MAJOR.MINOR.PATCH (for example 2.3.1): MAJOR for incompatible changes, MINOR for new, compatible features, PATCH for bug fixes. Pre-releases: 2.0.0-beta.1. Alternative CalVer (2026.03). The number appears in the tag, package file (package.json, pyproject.toml) and release.

Releases and changelog

On GitHub/GitLab a release creates from a tag a page with description, download files (artifacts) and automatically generated notes. A CHANGELOG.md (format “Keep a Changelog”) is structured by version into Added, Changed, Deprecated, Removed, Fixed, Security and addresses users, not developers (do not simply paste the commit list). With Conventional Commits and tools (release-please, semantic-release, changesets) versions and changelog can be produced automatically.

Procedure and tips

  1. Tests green, raise version, extend changelog.
  2. Commit, set tag, push.
  3. CI builds artifacts (packages, container images) and publishes (npm, PyPI, Docker registry), ideally reproducible and signed.
  4. Write release notes, clearly highlight breaking changes and give migration notes.
  5. On errors a new patch version instead of moving the tag. For websites a deployment per commit often suffices; tags/releases matter for libraries, apps and tools that others install.

See also: Semantic versioning, Conventional Commits, CI/CD pipeline, README file

Backlinks