Skip to content

version-generation.md

Latest commit

 

History

History
68 lines (54 loc) · 4.94 KB

version-generation.md

File metadata and controls

68 lines (54 loc) · 4.94 KB
Raw

Version generation

There are three modes to generate the next version:

  1. conventional commits (default) — next version determined based on commit message prefixes such as fix:, feat:, docs:, perf:. This mode allows to use all features of this action (see table below)
  2. version bump — (when pass version-bump input) allows to bump a version w/o special commit messages, useful in enterprise
  3. explicit version — (when pass verion input) provide a new version as explicit input
feature conventional commits version bump explicit version
update CHANGELOG.md ✅ ⚠️ ❌️
GH release ✅ ⚠️ ❌️
floating tags ✅ ✅ ✅
release channel ✅ ✅ ⚠️
prerelease ✅ ⚠️ ⚠️
maintenance releases ✅ ✅ ⚠️

Version bump

Semantic versioning makes most of sense when you do not know your customers, so you can say "this release is not risky, it is just a bugfix" or "this release comes with a new feature but doesn't break anything". In enterprise the software is being developed, deployed and tested by the same team, so teams often do not use conventional commits. All that matters — the version is bumped, artifacts are published. For such teams there is an option version-bump, it allows to bump a minor/patch version even if there are no special prefixes in commit messages

version-bump can take the following values:

  • (no-value) — default, meaning use "conventional commits" mode
  • default-patch — if no conventional commits, default to patch bump
  • default-minor — if no conventional commits, default to minor bump
  • (planned) patch — bump a patch version, ignore conventional commits
  • (planned) minor — bump a minor version, ignore conventional commits

⚠️ Notes:

  • CHANGELOG.md updated / GH release created only if there is a conventional commit(s)
  • See prerelease for details on how to make a first commit in the prerelease branch

After first commit values default-patch and default-minor behave identical — just increment number in suffix beta.1 -> beta.2

Explicit version

Alternatively to "conventional commits" and "version bump", you can provide an explicit version to be used for the release

This can be helpful in the following cases:

  • you have your own versioning scheme like yyyy-mm-dd-HH:mm:ss, Major.Minor or A.B.C.D
  • you do not want to release every time a PR is merged in the main branch, but rather want to release on demand
  • quick alternative instead of fully fledged prereleases or maintenance release
  • (rare, typically not recommended) you want to re-release an existing version

⚠️ Notes:

  • "explicit version" takes a release channel from release-channel input parameter ("conventional commits" and "version bump" take it from .releaserc.json file)
  • it is possible to do prerelease and maintenance releases in "explicit version", but agilecustoms/release action does not provide any assistance/guardrails

The table below shows how floating tags and release channel work in "explicit version" mode (default tag-format v${version} applies only to git tags; a leading v in explicit version is ignored, see the last row):

branch version floating tags channel git tags Docker tags and S3 dirs npm tag
main 1.2.4 false ⇒ v1.2.4 1.2.4 latest
main 1.3.0 false false ⇒ v1.3.0 1.3.0 main
main 2.0.0 false main ⇒ v2.0.0 2.0.0 main
main 2.1 false release ⇒ v2.1 2.1 release
main 1.2.4 true ⇒ v1.2.4, v1.2, v1, latest 1.2.4, 1.2, 1, latest latest
main 1.3.0 true false ⇒ v1.3.0, v1.3, v1 1.3.0, 1.3, 1 main
main 2.0.0 true main ⇒ v2.0.0, v2.0, v2 2.0.0, 2.0, 2, main main
main v2.1 true release ⇒ v2.1, v2, release 2.1, 2, release release