From 06e32738a3c565d606e69b3a5de7baeac98eb634 Mon Sep 17 00:00:00 2001 From: Paul Hatcherian <1835615+PaulHatch@users.noreply.github.com> Date: Wed, 25 Nov 2020 15:30:00 -0500 Subject: [PATCH] Add overview to documentation --- minor.drawio.svg | 130 +++++++++++++++++++++++++++ readme.md | 45 ++++++++++ tagging.drawio.svg | 205 ++++++++++++++++++++++++++++++++++++++++++ versioning.drawio.svg | 109 ++++++++++++++++++++++ 4 files changed, 489 insertions(+) create mode 100644 minor.drawio.svg create mode 100644 tagging.drawio.svg create mode 100644 versioning.drawio.svg diff --git a/minor.drawio.svg b/minor.drawio.svg new file mode 100644 index 0000000..7c3fa69 --- /dev/null +++ b/minor.drawio.svg @@ -0,0 +1,130 @@ + + + + + + + + + + + + + + + + + +
+
+
+ Tagged: v1.0.1 +
+
+
+ + + Tagged: v1.0.1 + + + + + + + +
+
+
+ v1.0.2+0 +
+
+
+ + + v1.0.2+0 + + + + + + + +
+
+
+ v1.1.0+0 +
+
+
+ + + v1.1.0+0 + + + + + + + +
+
+
+ v1.2.0+1 +
+
+
+ + + v1.2.0+1 + + + + + + + +
+
+
+ Implicit Versions +
+
+
+ + + Implic... + + + + + + + + +
+
+
+ Commit Message: +
+ + Updates (MINOR) + +
+
+
+ + + Commit Message:... + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file diff --git a/readme.md b/readme.md index 72ca7b5..e8557aa 100644 --- a/readme.md +++ b/readme.md @@ -13,6 +13,51 @@ commit messages are inspected to determine the type of version change the next version represents. Including the term `(MAJOR)` or `(MINOR)` in the commit message alters the type of change the next version will represent. +# Background + +Automatic versioning during a build presents a chicken-and-egg problem--we +want the version to increase by a single value between each release, but we +usually do not know at build time whether a new build will be released or not. +Generally a build is tagged as part of a release step after passing testing and +other quality controls, so if we want to use the version number in the build +itself, especially for a build triggered by a commit, we cannot rely on having +a proper tag for the build. Most CI systems offer a "build number", but this +does not correspond to our semantic version and relies on the state of the CI +tool. It is with this in mind that this tool was developed with the following +goals: + +- Allow the version to be injected into the build +- Derive the version only from the git repository itself +- Do not require the version to be maintained by hand +- Resolve the version deterministically for a given commit (see caveats below) +- Provide an easy mechanism for incrementing major and minor versions by developers + +The solution here is to calculate the _implicit_ next version based on the most +recently tagged version and the commit messages. This is in essence, what this +tool does. An additional value called the "increment" tracks the number of commits +since the last version change, allowing preview tags to be created. + +![Commits Graph](versioning.drawio.svg?raw=true) + +## Major and Minor Versions + +The commit messages for the span of commits from the last tag are checked for the +presence of the designated terms (`(MAJOR)` or `(MINOR)` by default), if a term +is encountered that commit is treated as the start of a major or minor version +instead of the default patch level. As with normal commits the implied version +will only increment by one value since the last tag regardless of how many major +or minor commits are encountered. Major commits override minor commits, so a set +of commits containing both will result in a major version increment. + +![Commits Graph](minor.drawio.svg?raw=true) + +## A Caveat Regarding Tags + +Please note that if a tag is assigned to an older commit, the commits that come +after it will be given the new new version, for example: + +![Commits Graph](tagging.drawio.svg?raw=true) + # Usage diff --git a/tagging.drawio.svg b/tagging.drawio.svg new file mode 100644 index 0000000..f33618a --- /dev/null +++ b/tagging.drawio.svg @@ -0,0 +1,205 @@ + + + + + + + + + + + + + + + + + +
+
+
+ Tagged: v1.0.1 +
+
+
+ + + Tagged: v1.0.1 + + + + + + + +
+
+
+ v1.0.2+0 +
+
+
+ + + v1.0.2+0 + + + + + + + +
+
+
+ v1.0.2+1 +
+
+
+ + + v1.0.2+1 + + + + + + + +
+
+
+ v1.0.2+2 +
+
+
+ + + v1.0.2+2 + + + + + + + + + + + + + + + + + +
+
+
+ Tagged: v1.0.1 +
+
+
+ + + Tagged: v1.0.1 + + + + + + + +
+
+
+ v1.0.2+0 +
+
+
+ + + v1.0.2+0 + + + + + + + +
+
+
+ v1.0.3+0 +
+
+
+ + + v1.0.3+0 + + + + + + + +
+
+
+ Tagged: v1.0.2 +
+
+
+ + + Tagged: v1.0.2 + + + + + + + +
+
+
+ Tag Applied +
+
+
+ + + Tag Applied + + + + + + + +
+
+
+ Implicit Version +
+ Changes +
+
+
+ + + Implicit Version... + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file diff --git a/versioning.drawio.svg b/versioning.drawio.svg new file mode 100644 index 0000000..abe5865 --- /dev/null +++ b/versioning.drawio.svg @@ -0,0 +1,109 @@ + + + + + + + + + + + + + + + + + +
+
+
+ Tagged: v1.0.1 +
+
+
+ + + Tagged: v1.0.1 + + + + + + + +
+
+
+ v1.0.2+0 +
+
+
+ + + v1.0.2+0 + + + + + + + +
+
+
+ v1.0.2+1 +
+
+
+ + + v1.0.2+1 + + + + + + + +
+
+
+ v1.0.2+2 +
+
+
+ + + v1.0.2+2 + + + + + + + +
+
+
+ Implicit Versions +
+
+
+ + + Implic... + + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file