docs: update formatter docs

Author: idc101

docs/common_patterns.md

@@ -9,7 +9,7 @@ Overview:
 - All releases are done from the master branch.
 - Only the master branch is tagged
 - Release Candidates are not used
--  Any version number not from master includes build metadata to indicate it is not an official release.
+- Any version number not from master includes build metadata to indicate it is not an official release.
 
 ### Controlling the next version number
 

docs/formats.md

@@ -17,7 +17,7 @@ The following built in formats conform to the SemVer spec. They cannot be overri
 
 | Format Token  | Substitution  |
 | ------------- | ------------- |
-| `Version` | `{x}.{y}.{z}` |
+| `Version` | `{Major}.{Minor}.{Patch}` |
 | `VersionPreRelease` | `{Version}-{PreRelease}` |
 | `VersionBuildMetaData` | `{Version}+{BuildMetaData}` |
 | `VersionPreReleaseBuildMetaData` | `{Version}-{PreRelease}+{BuildMetaData}` |
@@ -30,18 +30,21 @@ The following built in formats conform to the SemVer spec. They cannot be overri
 | `Next` | Full Semantic Version |
 | `Tag` | Full Semantic Version as a tag (includes the prefix) |
 | `TagMessage` | Tag Message |
-| `x` | Version major number |
-| `z` | Version patch number |
-| `y` | Version minor number |
-| `br` | Branch name |
-| `sh` | Short Hash |
-| `hash` | Full Hash |
+| `Major` | Version major number |
+| `Minor` | Version nimor number |
+| `Patch` | Version patch number |
+| `Branch` | Branch name |
+| `ShortHash` | Short Hash |
+| `FullHash` | Full Hash |
 | `dd` | Day |
 | `mm` | Month |
 | `yyyy` | Year |
-| `bn` | Build No from build system |
-| `tag?` | `true` if this branch is allowed to be tagged; `false` otherwise |
-| `pr` | Tag prefix |
+| `Tag?` | `true` if this branch is allowed to be tagged; `false` otherwise |
+| `Prefix` | Tag prefix |
 | `env.XXXX` | Environment Variables |
 
 ### Environment Variables
+
+All environment variables are available under a set of formats prefixed with `env.`.
+For example `{env.BUILD_NUMBER}` would get the `BUILD_NUMBER` environment variable.
+This is most useful for getting information from build systems.

docs/test.md

@@ -0,0 +1,58 @@
+## A test
+
+<script src="https://cdn.jsdelivr.net/npm/@gitgraph/js"></script>
+
+<div id="master-version-inc-container"></div>
+
+<!-- Use the `GitgraphJS` global variable to create your graph -->
+<script>
+var withoutHash = GitgraphJS.templateExtend(GitgraphJS.TemplateName.Metro, {
+    commit: {
+      message: {
+        displayHash: false,
+        displayAuthor: false,
+        font: "normal 10pt"
+      },
+      spacing: 40,
+      font: "8pt"
+    },
+    branch: {
+      spacing: 40,
+      label: {
+        font: "normal 10pt"
+      }
+    }
+});
+
+function f1() {
+    // Get the graph container HTML element.
+    const graphContainer = document.getElementById("master-version-inc-container");
+
+    // Instantiate the graph.
+    const gitgraph = GitgraphJS.createGitgraph(graphContainer, {
+      template: withoutHash,
+    });
+    
+    // Simulate git commands with Gitgraph API.
+    const master = gitgraph.branch("master");
+    master
+      .commit("some code").tag("v4.2.5")
+      .commit("feat: some more code").tag("v4.3.0")
+      .commit("fix: a fix")
+      .commit("feat: a feature").tag("v4.4.0")
+    
+    //const develop = gitgraph.branch("develop");
+    //develop.commit("Add TypeScript");
+    
+    //const aFeature = gitgraph.branch("a-feature");
+    //aFeature
+    //  .commit("feat: Make it work   <-- This will bump the minor version")
+    //  .commit("Make it right")
+    //  .commit("Make it fast");
+    
+    //develop.merge(aFeature);
+    //develop.commit("Prepare v1");
+    
+    //master.merge(develop).tag("v1.0.0");
+}
+</script>

src/main/scala/net/cardnell/mkver/Formatter.scala

@@ -47,7 +47,6 @@ object Formatter {
       Format("dd", version.date.getDayOfMonth.formatted("00")),
       Format("mm", version.date.getMonthValue.formatted("00")),
       Format("yyyy", version.date.getYear.toString),
-      Format("BuildNo", version.buildNo),
       Format("Tag?", branchConfig.tag.toString),
       Format("TagPrefix", branchConfig.tagPrefix.toString)
     ) ++ AppConfig.mergeFormats(branchConfig.formats, builtInFormats)

src/main/scala/net/cardnell/mkver/MkVer.scala

@@ -64,8 +64,7 @@ object MkVer {
         branch = currentBranch,
         commitHashShort = commitInfos.headOption.map(_.shortHash).getOrElse(""),
         commitHashFull = commitInfos.headOption.map(_.fullHash).getOrElse(""),
-        date = LocalDate.now(),
-        buildNo = sys.env.getOrElse("BUILD_BUILDNUMBER", "TODO")
+        date = LocalDate.now()
       )
     }
   }

src/main/scala/net/cardnell/mkver/Version.scala

@@ -49,5 +49,4 @@ case class VersionData(major: Int,
                        branch: String,
                        commitHashShort: String,
                        commitHashFull: String,
-                       date: LocalDate,
-                       buildNo: String)
+                       date: LocalDate)

src/test/scala/net/cardnell/mkver/FormatterSpec.scala

@@ -26,7 +26,7 @@ object FormatterSpec extends DefaultRunnableSpec {
       assert(Formatter.branchNameToVariable("refs/heads/feat/f1"))(equalTo("feat-f1"))
     },
     test("should format default variables") {
-      val versionData = VersionData(1,2,3,4,"feature/f1", "abcd", "abcdefg", LocalDate.now(), "56")
+      val versionData = VersionData(1,2,3,4,"feature/f1", "abcd", "abcdefg", LocalDate.now())
       val branchConfig = BranchConfig(".*", "Version", true, "v", "release {Version}", "RC", Nil, Nil)
       val formatter = Formatter(versionData, branchConfig)
       assert(formatter.format("{Major}"))(equalTo("1")) &&

src/test/scala/net/cardnell/mkver/MkVerSpec.scala

@@ -55,8 +55,8 @@ object MkVerSpec extends DefaultRunnableSpec {
     ),
     suite("formatTag")(
       testM("should format tag") {
-        val versionData = VersionData(1,2,3,4,"feature/f1", "abcd", "abcdefg", LocalDate.now(), "56")
-        val branchConfig = BranchConfig(".*", "Version", true, "v", "release {Version}", "RC", List(Format("Version", "{x}.{y}.{z}")), Nil)
+        val versionData = VersionData(1,2,3,4,"feature/f1", "abcd", "abcdefg", LocalDate.now())
+        val branchConfig = BranchConfig(".*", "Version", true, "v", "release {Version}", "RC", List(Format("Version", "{Major}.{Minor}.{Patch}")), Nil)
         assertM(formatTag(branchConfig, versionData))(equalTo("v1.2.3"))
       }
     )