Project: Release and CHANGELOG

Introduction

Shipping a version ties Git tags, package version numbers, release notes, and optional GitHub Releases together. This project bumps a semver, updates CHANGELOG.md, tags v1.0.0, pushes, and publishes a release—mirroring how Maven, Gradle, and npm projects ship.

Prerequisites

Prepare CHANGELOG

Create or update CHANGELOG.md:

Format inspired by Keep a Changelog.

Commit unreleased section separately during development; move items into version section at release time.

Bump Package Version (Pick Your Stack)

npm / Node

bash
npm version 1.0.0 -m "chore: release v1.0.0"

Code explanation:

  • Updates package.json, commits, creates v1.0.0 tag

Maven

Edit pom.xml:

xml
<version>1.0.0</version>
bash
git add pom.xml CHANGELOG.md
git commit -m "chore: release v1.0.0"
git tag -a v1.0.0 -m "Release 1.0.0"

Gradle

gradle
version = '1.0.0'

Same commit + tag flow as Maven.

Align tag name v1.0.0 with package version 1.0.0.

Finalize CHANGELOG for Release

Move [Unreleased] items into [1.0.0] section; leave empty [Unreleased] heading.

bash
git add CHANGELOG.md
git commit -m "docs: finalize changelog for v1.0.0"

If npm version already committed, amend or single release commit—avoid duplicate tags.

Push Branch and Tag

bash
git push origin main
git push origin v1.0.0

Verify tag on GitHub Tags tab.

Create GitHub Release

  1. Releases → Draft a new release
  2. Choose tag v1.0.0
  3. Title: v1.0.0
  4. Description: copy [1.0.0] section from CHANGELOG
  5. Attach build artifact if applicable (JAR, zip)
  6. Publish

Optional CI workflow builds artifact on tag push—see Git and CI/CD.

Patch Release Drill

After bugfix on main:

  1. Bump to 1.0.1
  2. Add CHANGELOG section
  3. Tag v1.0.1, push, release

SemVer patch = backward-compatible fix.

Checklist

  • CHANGELOG.md documents user-visible changes
  • Package version matches tag (minus v prefix)
  • Tag pushed to remote
  • GitHub Release published with notes

FAQ

Tag exists locally not remote?

git push origin v1.0.0.

npm version wrong tag?

git tag -d v1.0.0 locally, fix, retag carefully—never retag public releases casually.

CHANGELOG vs commit messages?

Commits for developers; CHANGELOG curated for users—group related commits.

Pre-release versions?

Use 1.0.0-beta.1 tag for testers—document in CHANGELOG.

Monorepo versions?

Each package may tag independently—advanced; single package first.

Deploy from tag?

Many pipelines checkout tag SHA for reproducible builds—tie to Nginx deploy after CI build.