Versions, releases, and monorepos

Tags and releases

A tag is a fixed label that marks a specific commit, usually to point at a published version. Unlike a branch, it doesn't move.

git tag v1.4.0                 # lightweight tag on the current commit
git tag -a v1.4.0 -m "Release 1.4.0"   # annotated tag (with author and message)
git push origin v1.4.0         # publish the tag (push doesn't send tags by default)
git push origin --tags         # publish all tags

A release is the formal publication of a version: the tag + change notes (changelog) + artifacts (binaries, packages). On GitHub it's created from a tag.

Semantic versioning (SemVer)

SemVer assigns each version three numbers: MAJOR.MINOR.PATCH (e.g. 2.4.1). Each one communicates the type of change:

• MAJOR: incompatible changes (break the public API). Bumping MAJOR resets MINOR and PATCH to 0. 2.4.1 -> 3.0.0.
• MINOR: new backward-compatible feature. Resets PATCH to 0. 2.4.1 -> 2.5.0.
• PATCH: compatible bug fixes. 2.4.1 -> 2.4.2.

~1.2.3  -> allows PATCH:  >=1.2.3 <1.3.0
^1.2.3  -> allows MINOR:  >=1.2.3 <2.0.0   (default in npm)

It fits with Conventional Commits: fix: -> PATCH, feat: -> MINOR, feat!: / BREAKING CHANGE -> MAJOR.

Monorepo vs polyrepo

• Polyrepo: one repository per project/package. Clear isolation and per-repo permissions, but sharing code and coordinating changes across repos is more costly.
• Monorepo: many projects/packages in a single repository. It makes it easy to share code, do atomic refactors that cross packages, and have a single source of truth. In exchange, it requires tooling (Nx, Turborepo, pnpm/npm workspaces) and a good CI so you don't build/test everything on each change.

my-monorepo/
├── package.json        # workspaces
├── apps/
│   ├── web/
│   └── api/
└── packages/
    ├── ui/
    └── utils/

There's no universal "winner": the monorepo shines when the packages are tightly coupled and are versioned/deployed together; the polyrepo, when they are independent and managed by separate teams.