Git Workflow: Release Process

Follow these instructions to safely and consistently release a new version of the project.

1. Verify Clean Workspace and Tests

• Ensure there are no untracked files or uncommitted changes (unless they are part of the release).
• Ensure all tests pass (npm test or the language equivalent).

2. Update Documentation

• README.md: Ensure the README.md reflects any new features, installation steps, or usage examples introduced since the last release.
• CHANGELOG.md:
  • Add a new section at the top of the changelog for the new version (e.g., ## [1.2.0] - YYYY-MM-DD).
  • Categorize changes into Added, Changed, Deprecated, Removed, Fixed, or Security.
  • Review recent commit messages (git log) to capture all user-facing changes.

3. Bump the Version Number

• Consult the current version using package.json (or the language equivalent, such as pyproject.toml or Cargo.toml).
• Determine the new version number using Semantic Versioning (SemVer):
  • MAJOR version for incompatible API changes.
  • MINOR version for adding functionality in a backward-compatible manner.
  • PATCH version for backward-compatible bug fixes.
• Update the version number in all necessary files. For Node.js projects, use npm version <major|minor|patch> --no-git-tag-version if appropriate, or edit package.json manually.

4. Commit the Release Changes

• Stage the package.json, CHANGELOG.md, README.md, and any other updated metadata files.
• Commit with a standard release message subject, and explicitly list the summarized release changes (e.g. from the CHANGELOG.md) in the commit body using a multi-line format or multiple -m flags:

  git commit -m "chore(release): bump version to v<NEW_VERSION>" -m "Changed: Updated dependencies and added SemVer guidelines."

5. Tag the Release

• Create an annotated git tag for the new version.

  git tag -a v<NEW_VERSION> -m "Release v<NEW_VERSION>"

6. Push Changes

• Push the release commit and the new tag to the remote repository.

  git push origin main
  git push origin v<NEW_VERSION>

• Note: Replace main with the appropriate default branch if different.

Edge Cases

• Hotfixes: If releasing a critical bug fix, bump the PATCH version and ensure the changelog explicitly calls out the fix.
• Pre-releases: Use -alpha, -beta, or -rc suffixes (e.g., 1.2.0-beta.1) if preparing a pre-release version for testing.