feat: Support fallback environment source branch

.gitignore

@@ -13,3 +13,4 @@ testResults.xml
 coverage.xml
 coverage.cobertura.xml
 *.trx
+*.DotSettings.user

src/SimpleVersion.Abstractions/Environment/BaseVersionEnvironment.cs

@@ -1,7 +1,7 @@
 // Licensed under the MIT license. See https://kieranties.mit-license.org/ for full license information.
 
 using System;
-using SimpleVersion.Pipeline;
+using System.Text.RegularExpressions;
 
 namespace SimpleVersion.Environment
 {
@@ -10,20 +10,30 @@ namespace SimpleVersion.Environment
     /// </summary>
     public abstract class BaseVersionEnvironment : IVersionEnvironment
     {
+        /// <summary>
+        /// Use to normalize branch names from a canonical name.
+        /// </summary>
+        protected static readonly Regex CanonicalBranchTrimmer = new Regex(@"^refs\/(heads\/)?", RegexOptions.IgnoreCase);
+
         /// <summary>
         /// Initializes a new instance of the <see cref="BaseVersionEnvironment"/> class.
         /// </summary>
         /// <param name="accessor">The accessor for environment variables.</param>
-        public BaseVersionEnvironment(IEnvironmentVariableAccessor accessor)
+        protected BaseVersionEnvironment(IEnvironmentVariableAccessor accessor)
         {
             Variables = accessor ?? throw new ArgumentNullException(nameof(accessor));
+            CanonicalBranchName = Variables.GetVariable("simpleversion.sourcebranch");
+            if (CanonicalBranchName != null)
+            {
+                BranchName = CanonicalBranchTrimmer.Replace(CanonicalBranchName, string.Empty);
+            }
         }
 
         /// <inheritdoc/>
-        public abstract string? CanonicalBranchName { get; }
+        public string? CanonicalBranchName { get; protected set; }
 
         /// <inheritdoc/>
-        public abstract string? BranchName { get; }
+        public string? BranchName { get; protected set; }
 
         /// <inheritdoc/>
         public abstract bool IsValid { get; }

src/SimpleVersion.Core/Environment/AzureDevopsEnvironment.cs

@@ -10,28 +10,23 @@ namespace SimpleVersion.Environment
     /// </summary>
     public class AzureDevopsEnvironment : BaseVersionEnvironment
     {
-        private static readonly Regex _trim = new Regex(@"^refs\/(heads\/)?", RegexOptions.IgnoreCase);
-
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureDevopsEnvironment"/> class.
         /// </summary>
         /// <param name="accessor">The accessor for environment variables.</param>
         public AzureDevopsEnvironment(IEnvironmentVariableAccessor accessor)
             : base(accessor)
         {
-            CanonicalBranchName = Variables.GetVariable("BUILD_SOURCEBRANCH");
-            if (CanonicalBranchName != null)
+            if (string.IsNullOrWhiteSpace(CanonicalBranchName))
             {
-                BranchName = _trim.Replace(CanonicalBranchName, string.Empty);
+                CanonicalBranchName = Variables.GetVariable("BUILD_SOURCEBRANCH");
+                if (CanonicalBranchName != null)
+                {
+                    BranchName = CanonicalBranchTrimmer.Replace(CanonicalBranchName, string.Empty);
+                }
             }
         }
 
-        /// <inheritdoc/>
-        public override string? CanonicalBranchName { get; }
-
-        /// <inheritdoc/>
-        public override string? BranchName { get; }
-
         /// <inheritdoc/>
         public override bool IsValid => Variables.GetVariable("TF_BUILD").ToBool();
     }

src/SimpleVersion.Core/Environment/DefaultVersionEnvironment.cs

@@ -15,12 +15,6 @@ public DefaultVersionEnvironment(IEnvironmentVariableAccessor accessor) : base(a
         {
         }
 
-        /// <inheritdoc/>
-        public override string? CanonicalBranchName => null;
-
-        /// <inheritdoc/>
-        public override string? BranchName => null;
-
         /// <inheritdoc/>
         public override bool IsValid => true;
     }

src/SimpleVersion.Docs/site/articles/environments.md

@@ -0,0 +1,26 @@
+Environments
+============
+
+SimpleVersion attempts to identify git information from the local environment.
+When running on Continuous Integration (CI) systems you may need to prepare the
+environment to cater for the CI systems specific approach to builds.
+
+Azure Devops
+------------
+
+Azure Devops is identified as the build environment when the environment variable `TF_BUILD` is set.
+
+When identified, the canonical and friendly branch names are derived from the `BUILD_SOURCEBRANCH` environment variable.
+
+Fallback Environment
+--------------------
+
+For all environments, the build branch can be overridden by setting `simpleversion.sourcebranch` to the _full canonical branch name_.  When this variable is set it will override the resolution from any CI system as well as the local repository branch name.
+
+### TeamCity
+
+When building with TeamCity you can lift the branch name of the build to an environment variable by doing the following:
+
+1. Open your build configuration, and select Parameters
+1. Add a new paramter called `env.simpleversion.sourcebranch`
+1. Set the value to `%teamcity.build.vcs.branch.{vcsid}%` where `{vcsid}` is the VCS Root of your repo

src/SimpleVersion.Docs/site/articles/toc.yml

@@ -2,5 +2,7 @@
   href: intro.md
 - name: Configuration
   href: configuration.md
+- name: Environments
+  href: environments.md
 - name: Results
   href: results.md

test/SimpleVersion.Abstractions.Tests/Environment/BaseVersionEnvironmentFixture.cs

@@ -34,16 +34,28 @@ public void Ctor_WithAccessor_SetsProperty()
             instance.VariablesWrapper.Should().BeSameAs(accessor);
         }
 
+        [Fact]
+        public void BranchName_OverrideSet_ReturnsOverride()
+        {
+            // Arrange
+            var expectedName = "OVERRIDE";
+            var accessor = Substitute.For<IEnvironmentVariableAccessor>();
+            accessor.GetVariable("simpleversion.sourcebranch").Returns(expectedName);
+            var sut = new StubVersionEnvironment(accessor);
+
+            // Act
+            var result = sut.BranchName;
+
+            // Assert
+            result.Should().Be(expectedName);
+        }
+
         private class StubVersionEnvironment : BaseVersionEnvironment
         {
             public StubVersionEnvironment(IEnvironmentVariableAccessor accessor) : base(accessor)
             {
             }
 
-            public override string CanonicalBranchName => throw new NotImplementedException("Should not be tested");
-
-            public override string BranchName => throw new NotImplementedException("Should not be tested");
-
             public override bool IsValid => throw new NotImplementedException("Should not be tested");
 
             public IEnvironmentVariableAccessor VariablesWrapper => Variables;

test/SimpleVersion.Core.Tests/Environment/AzureDevopsEnvironmentFixture.cs

@@ -102,5 +102,25 @@ public void BranchName_ReadsCorrectVariable(string canonical, string branch)
             // Assert
             result.Should().Be(branch);
         }
+
+        [Theory]
+        [InlineData("refs/heads/master")]
+        [InlineData("refs/heads/release/1.0/master")]
+        [InlineData("refs/pull/10/merge")]
+        public void BranchName_OverrideSet_ReturnsOverride(string canonical)
+        {
+            // Arrange
+            var expectedName = "override";
+            _env.GetVariable("simpleversion.sourcebranch").Returns(expectedName);
+            _env.GetVariable("BUILD_SOURCEBRANCH").Returns(canonical);
+
+            var sut = new AzureDevopsEnvironment(_env);
+
+            // Act
+            var result = sut.BranchName;
+
+            // Assert
+            result.Should().Be(expectedName);
+        }
     }
 }

test/SimpleVersion.Core.Tests/Environment/DefaultVersionEnvironmentFixture.cs

@@ -15,6 +15,7 @@ public class DefaultVersionEnvironmentFixture
         public DefaultVersionEnvironmentFixture()
         {
             _env = Substitute.For<IEnvironmentVariableAccessor>();
+            _env.GetVariable("simpleversion.sourcebranch").Returns((string)null);
         }
 
         [Fact]
@@ -66,5 +67,20 @@ public void BranchName_ReturnsNull()
             // Assert
             result.Should().BeNull();
         }
+
+        [Fact]
+        public void BranchName_OverrideSet_ReturnsOverride()
+        {
+            // Arrange
+            var expectedName = "OVERRIDE";
+            _env.GetVariable("simpleversion.sourcebranch").Returns(expectedName);
+            var sut = new DefaultVersionEnvironment(_env);
+
+            // Act
+            var result = sut.BranchName;
+
+            // Assert
+            result.Should().Be(expectedName);
+        }
     }
 }