Merge pull request #1029 from JakeGinnivan/namedBranchConfigs

Named branch configuration

Author: JakeGinnivan

BREAKING CHANGES.md

@@ -1,3 +1,14 @@
+v4.0.0
+ - When using GitFlow, a few things have changed. Hopefully the new settings just work for you
+    - develop has pre-release tag of `alpha` now, not unstable
+    - develop will bump as soon as a release branch is created
+    - Look at the [GitFlow examples](http://gitversion.readthedocs.io/en/latest/git-branching-strategies/gitflow-examples/) for details of how it works now
+ - Regex's are no longer used as keys in branch config
+    - We have named branches, and introduced a `regex` config which you can override.
+    - The default keys are: master, develop, feature, release, pull-request, hotfix, support
+    - Just run GitVersion.exe in your project directory and it will tell you what to change your config keys to
+    - For example, `dev(elop)?(ment)?$` is now just `develop`, we suggest not overring regex's unless you really want to use a different convention.
+
 v3.0.0
  - NextVersion.txt has been deprecated, only GitVersionConfig.yaml is supported
  - `AssemblyFileSemVer` variable removed, AssemblyVersioningScheme configuration value makes this variable obsolete

docs/configuration.md

@@ -126,7 +126,21 @@ The header for ignore configuration.
 
 #### sha
 A sequence of SHAs to be excluded from the version calculations. Useful when
-there is a rogue commit in history yielding a bad version.
+there is a rogue commit in history yielding a bad version. You can use either style below:
+
+```
+ignore:
+  sha: [e7bc24c0f34728a25c9187b8d0b041d935763e3a, 764e16321318f2fdb9cdeaa56d1156a1cba307d7]
+```
+
+or
+
+```
+ignore:
+  sha:
+    - e7bc24c0f34728a25c9187b8d0b041d935763e3a
+    - 764e16321318f2fdb9cdeaa56d1156a1cba307d7
+```
 
 #### commits-before
 Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before:
@@ -136,33 +150,41 @@ Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before:
 ## Branch configuration
 Then we have branch specific configuration, which looks something like this:
 
+**NOTE: ** v4 changed from using regexes for keys, to named configs
+
+If you have branch specific configuration upgrading to v4 will force you to upgrade.
+
 ```yaml
 branches:
   master:
+    regex: master
     mode: ContinuousDelivery
     tag: ''
     increment: Patch
     prevent-increment-of-merged-branch-version: true
     track-merge-target: false
     is-develop: false
     is-release-branch: false
-  releases?[/-]:
+  release:
+    regex: releases?[/-]
     mode: ContinuousDelivery
     tag: beta
     increment: Patch
     prevent-increment-of-merged-branch-version: true
     track-merge-target: false
     is-develop: false
     is-release-branch: true
-  features?[/-]:
+  feature:
+    regex: features?[/-]
     mode: ContinuousDelivery
     tag: useBranchName
     increment: Inherit
     prevent-increment-of-merged-branch-version: false
     track-merge-target: false
     is-develop: false
     is-release-branch: false
-  (pull|pull\-requests|pr)[/-]:
+  pull-request:
+    regex: (pull|pull\-requests|pr)[/-]
     mode: ContinuousDelivery
     tag: PullRequest
     increment: Inherit
@@ -171,23 +193,26 @@ branches:
     track-merge-target: false
     is-develop: false
     is-release-branch: false
-  hotfix(es)?[/-]:
+  hotfix:
+    regex: hotfix(es)?[/-]
     mode: ContinuousDelivery
     tag: beta
     increment: Patch
     prevent-increment-of-merged-branch-version: false
     track-merge-target: false
     is-develop: false
     is-release-branch: false
-  support[/-]:
+  support:
+    regex: support[/-]
     mode: ContinuousDelivery
     tag: ''
     increment: Patch
     prevent-increment-of-merged-branch-version: true
     track-merge-target: false
     is-develop: false
     is-release-branch: false
-  dev(elop)?(ment)?$:
+  develop:
+    regex: dev(elop)?(ment)?$
     mode: ContinuousDeployment
     tag: unstable
     increment: Minor
@@ -197,9 +222,14 @@ branches:
     is-release-branch: false
 ```
 
+If you don't specify the regex the inbuilt for that branch config will be used (recommended)
+
 We don't envision many people needing to change most of these configuration
 values, but here they are if you need to:
 
+### regex
+This is the regex which is used to match the current branch to the correct branch configuration.
+
 ### branches
 The header for all the individual branch configuration.
 
@@ -239,7 +269,7 @@ the branch is configured to use ContinuousDeployment mode.
 
 ```yaml
 branches:
-  (pull|pull\-requests|pr)[/-]:
+  pull-request:
     mode: ContinuousDeployment
     tag: PullRequest
     increment: Inherit

src/GitVersionCore.Tests/ConfigProviderTests.CanWriteOutEffectiveConfiguration.approved.txt

@@ -17,61 +17,68 @@ branches:
     increment: Patch
     prevent-increment-of-merged-branch-version: true
     track-merge-target: false
+    regex: master
     is-develop: false
     is-release-branch: false
     is-mainline: true
-  releases?[/-]:
+  release:
     mode: ContinuousDelivery
     tag: beta
     increment: Patch
     prevent-increment-of-merged-branch-version: true
     track-merge-target: false
+    regex: releases?[/-]
     is-develop: false
     is-release-branch: true
     is-mainline: false
-  features?[/-]:
+  feature:
     mode: ContinuousDelivery
     tag: useBranchName
     increment: Inherit
     prevent-increment-of-merged-branch-version: false
     track-merge-target: false
+    regex: features?[/-]
     is-develop: false
     is-release-branch: false
     is-mainline: false
-  (pull|pull\-requests|pr)[/-]:
+  pull-request:
     mode: ContinuousDelivery
     tag: PullRequest
     increment: Inherit
     prevent-increment-of-merged-branch-version: false
     tag-number-pattern: '[/-](?<number>\d+)[-/]'
     track-merge-target: false
+    regex: (pull|pull\-requests|pr)[/-]
     is-develop: false
     is-release-branch: false
     is-mainline: false
-  hotfix(es)?[/-]:
+  hotfix:
     mode: ContinuousDelivery
     tag: beta
     increment: Patch
     prevent-increment-of-merged-branch-version: false
     track-merge-target: false
+    regex: hotfix(es)?[/-]
     is-develop: false
     is-release-branch: false
     is-mainline: false
-  support[/-]:
+  support:
     mode: ContinuousDelivery
     tag: ''
     increment: Patch
     prevent-increment-of-merged-branch-version: true
     track-merge-target: false
+    regex: support[/-]
     is-develop: false
     is-release-branch: false
     is-mainline: true
-  dev(elop)?(ment)?$:
+  develop:
     mode: ContinuousDeployment
     tag: alpha
     increment: Minor
     prevent-increment-of-merged-branch-version: false
     track-merge-target: true
+    regex: dev(elop)?(ment)?$
     is-develop: true
     is-release-branch: false
     is-mainline: false

src/GitVersionCore.Tests/ConfigProviderTests.cs

@@ -29,46 +29,28 @@ public void Setup()
     }
 
     [Test]
-    public void CanReadDocumentAndMigrate()
+    public void CanReadOldDocument()
     {
         const string text = @"
-assembly-versioning-scheme: MajorMinor
-next-version: 2.0.0
-tag-prefix: '[vV|version-]'
-mode: ContinuousDelivery
+assemblyVersioningScheme: MajorMinor
+develop-branch-tag: alpha
+release-branch-tag: rc
 branches:
-    develop:
+    master:
+        mode: ContinuousDeployment
+    dev(elop)?(ment)?$:
         mode: ContinuousDeployment
         tag: dev
     release[/-]:
        mode: continuousDeployment
-       tag: rc 
-";
-        SetupConfigFileContent(text);
-
-        var config = ConfigurationProvider.Provide(repoPath, fileSystem);
-        config.AssemblyVersioningScheme.ShouldBe(AssemblyVersioningScheme.MajorMinor);
-        config.AssemblyInformationalFormat.ShouldBe(null);
-        config.NextVersion.ShouldBe("2.0.0");
-        config.TagPrefix.ShouldBe("[vV|version-]");
-        config.VersioningMode.ShouldBe(VersioningMode.ContinuousDelivery);
-        config.Branches["dev(elop)?(ment)?$"].Tag.ShouldBe("dev");
-        config.Branches["releases?[/-]"].Tag.ShouldBe("rc");
-        config.Branches["releases?[/-]"].VersioningMode.ShouldBe(VersioningMode.ContinuousDeployment);
-        config.Branches["dev(elop)?(ment)?$"].VersioningMode.ShouldBe(VersioningMode.ContinuousDeployment);
-    }
-
-    [Test]
-    public void CanReadOldDocument()
-    {
-        const string text = @"
-assemblyVersioningScheme: MajorMinor
-develop-branch-tag: alpha
-release-branch-tag: rc
+       tag: rc
 ";
         SetupConfigFileContent(text);
         var error = Should.Throw<OldConfigurationException>(() => ConfigurationProvider.Provide(repoPath, fileSystem));
         error.Message.ShouldContainWithoutWhitespace(@"GitVersion configuration file contains old configuration, please fix the following errors:
+GitVersion branch configs no longer are keyed by regexes, update:
+    dev(elop)?(ment)?$  -> develop
+    release[/-]         -> release
 assemblyVersioningScheme has been replaced by assembly-versioning-scheme
 develop-branch-tag has been replaced by branch specific configuration.See http://gitversion.readthedocs.org/en/latest/configuration/#branch-configuration
 release-branch-tag has been replaced by branch specific configuration.See http://gitversion.readthedocs.org/en/latest/configuration/#branch-configuration");
@@ -81,16 +63,16 @@ public void OverwritesDefaultsWithProvidedConfig()
         const string text = @"
 next-version: 2.0.0
 branches:
-    dev(elop)?(ment)?$:
+    develop:
         mode: ContinuousDeployment
         tag: dev";
         SetupConfigFileContent(text);
         var config = ConfigurationProvider.Provide(repoPath, fileSystem);
 
         config.NextVersion.ShouldBe("2.0.0");
-        config.Branches["dev(elop)?(ment)?$"].Increment.ShouldBe(defaultConfig.Branches["dev(elop)?(ment)?$"].Increment);
-        config.Branches["dev(elop)?(ment)?$"].VersioningMode.ShouldBe(defaultConfig.Branches["dev(elop)?(ment)?$"].VersioningMode);
-        config.Branches["dev(elop)?(ment)?$"].Tag.ShouldBe("dev");
+        config.Branches["develop"].Increment.ShouldBe(defaultConfig.Branches["develop"].Increment);
+        config.Branches["develop"].VersioningMode.ShouldBe(defaultConfig.Branches["develop"].VersioningMode);
+        config.Branches["develop"].Tag.ShouldBe("dev");
     }
 
     [Test]
@@ -99,13 +81,26 @@ public void CanRemoveTag()
         const string text = @"
 next-version: 2.0.0
 branches:
-    releases?[/-]:
+    release:
         tag: """"";
         SetupConfigFileContent(text);
         var config = ConfigurationProvider.Provide(repoPath, fileSystem);
 
         config.NextVersion.ShouldBe("2.0.0");
-        config.Branches["releases?[/-]"].Tag.ShouldBe(string.Empty);
+        config.Branches["release"].Tag.ShouldBe(string.Empty);
+    }
+
+    [Test]
+    public void RegexIsRequired()
+    {
+        const string text = @"
+next-version: 2.0.0
+branches:
+    bug:
+        tag: bugfix";
+        SetupConfigFileContent(text);
+        var ex = Should.Throw<GitVersionConfigurationException>(() => ConfigurationProvider.Provide(repoPath, fileSystem));
+        ex.Message.ShouldBe("Branch configuration 'bug' is missing required configuration 'regex'");
     }
 
     [Test]
@@ -114,12 +109,14 @@ public void CanProvideConfigForNewBranch()
         const string text = @"
 next-version: 2.0.0
 branches:
-    bug[/-]:
+    bug:
+        regex: 'bug[/-]'
         tag: bugfix";
         SetupConfigFileContent(text);
         var config = ConfigurationProvider.Provide(repoPath, fileSystem);
 
-        config.Branches["bug[/-]"].Tag.ShouldBe("bugfix");
+        config.Branches["bug"].Regex.ShouldBe("bug[/-]");
+        config.Branches["bug"].Tag.ShouldBe("bugfix");
     }
 
     [Test]
@@ -216,8 +213,8 @@ public void CanReadDefaultDocument()
         var config = ConfigurationProvider.Provide(repoPath, fileSystem);
         config.AssemblyVersioningScheme.ShouldBe(AssemblyVersioningScheme.MajorMinorPatch);
         config.AssemblyInformationalFormat.ShouldBe(null);
-        config.Branches["dev(elop)?(ment)?$"].Tag.ShouldBe("alpha");
-        config.Branches["releases?[/-]"].Tag.ShouldBe("beta");
+        config.Branches["develop"].Tag.ShouldBe("alpha");
+        config.Branches["release"].Tag.ShouldBe("beta");
         config.TagPrefix.ShouldBe(ConfigurationProvider.DefaultTagPrefix);
         config.NextVersion.ShouldBe(null);
     }

src/GitVersionCore.Tests/GitVersionContextTests.cs

@@ -40,7 +40,7 @@ public void UsesBranchSpecificConfigOverTopLevelDefaults()
                 Branches =
                 {
                     {
-                        "dev(elop)?(ment)?$", new BranchConfig
+                        "develop", new BranchConfig
                         {
                             VersioningMode = VersioningMode.ContinuousDeployment,
                             Tag = "alpha"
@@ -69,8 +69,8 @@ public void CanFindParentBranchForInheritingIncrementStrategy()
             {
                 Branches =
                 {
-                    { "dev(elop)?(ment)?$", new BranchConfig { Increment = IncrementStrategy.Major} },
-                    { "features?[/-]", new BranchConfig { Increment = IncrementStrategy.Inherit} }
+                    { "develop", new BranchConfig { Increment = IncrementStrategy.Major} },
+                    { "feature", new BranchConfig { Increment = IncrementStrategy.Inherit} }
                 }
             }.ApplyDefaults();
 

src/GitVersionCore.Tests/IntegrationTests/DevelopScenarios.cs

@@ -62,7 +62,7 @@ public void CanChangeDevelopTagViaConfig()
             Branches =
             {
                 {
-                    "dev(elop)?(ment)?$", new BranchConfig
+                    "develop", new BranchConfig
                     {
                         Tag = "alpha"
                     }
@@ -128,7 +128,7 @@ public void CanHandleContinuousDelivery()
         {
             Branches =
             {
-                {"dev(elop)?(ment)?$", new BranchConfig
+                {"develop", new BranchConfig
                 {
                     VersioningMode = VersioningMode.ContinuousDelivery
                 }