aj-geddes/semantic-versioning

Semantic Versioning

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Establish semantic versioning practices to maintain consistent version numbering aligned with release significance, enabling automated version management and release notes generation.

When to Use

• Package and library releases
• API versioning
• Version bumping automation
• Release note generation
• Breaking change tracking
• Dependency management
• Changelog management

Quick Start

Minimal working example:

# package.json
{
  "name": "my-awesome-package",
  "version": "1.2.3",
  "description": "An awesome package",
  "main": "dist/index.js",
  "repository": { "type": "git", "url": "https://github.com/org/repo.git" },
  "scripts": { "release": "semantic-release" },
  "devDependencies":
    {
      "semantic-release": "^21.0.0",
      "@semantic-release/changelog": "^6.0.0",
      "@semantic-release/git": "^10.0.0",
      "@semantic-release/github": "^9.0.0",
      "conventional-changelog-cli": "^3.0.0",
    },
}

Reference Guides

Detailed implementations in the references/ directory:

| Guide | Contents | |---|---| | Semantic Versioning Configuration | Semantic Versioning Configuration | | Conventional Commits Format | Conventional Commits Format | | Semantic Release Configuration | Semantic Release Configuration | | Version Bumping Script | Version Bumping Script | | Changelog Generation | Changelog Generation |

Best Practices

✅ DO

• Follow strict MAJOR.MINOR.PATCH format
• Use conventional commits
• Automate version bumping
• Generate changelogs automatically
• Tag releases in git
• Document breaking changes
• Use prerelease versions for testing

❌ DON'T

• Manually bump versions inconsistently
• Skip breaking change documentation
• Use arbitrary version numbering
• Mix features in patch releases