Merge pull request #989 from asbjornu/feature/mode-documentation-cleanup

Mode and configuration documentation cleanup

Author: JakeGinnivan

docs/configuration.md

@@ -1,26 +1,58 @@
 # Continuous Delivery
-Continuous delivery is the practice of having a deployment pipeline. Each stage of the pipeline gets the code going through the pipeline closer to production.
+Continuous Delivery is the practice of having a deployment pipeline and is the
+default mode in GitVersion. Each stage of the pipeline gets the code going
+through the pipeline closer to production.
 
-The topic itself is rather large, here we will just focus on the building and creation of *releasable* artifacts. This is only a part of continuous delivery as a whole, with the hard part being the ability to measure the impacts of what you have deployed into production.
+The topic itself is rather large, here we will just focus on the building and
+creation of *releasable* artifacts. This is only a part of continuous delivery
+as a whole, with the hard part being the ability to measure the impacts of what
+you have deployed into production.
 
 In essence continuous delivery means:
 
  - Your code is automatically built and tested
- - If any of the automated tests fail, the teams #1 priority is to fix the build
+ - If any of the automated tests fail, the team's #1 priority is to fix the
+   build
  - If the build is green, the application can be deployed at any time
    - Ideally the business should make that decision
    - The same artifacts which were built and tested should be deployed
    - That means no rebuilding everything when you are deploying
 
-Continuous delivery does not work well with GitFlow. The reason is that you are required to *merge* to master to do a release, triggering a rebuild and a new set of artifacts to go through your pipeline. Depending on how long your pipeline is, this could be a while.
-
-GitHubFlow is a better fit for Continuous delivery, the [mainline development](mainline-development.md) model means that every merged feature branch will be built as a *stable* version and if the build/builds go green then you are free to deploy to production at any time.
-
-## How continuous delivery affects GitVersion
-The thing about continuous delivery is that there will be *multiple* candidates to deploy to production and it is a human choice to deploy. This means that GitVersion will build **the same semantic version** until that version is deployed.
-
-GitVersion assumes Continuous Delivery by default in it's [configuration](../configuration.md), if you want to do [continuous deployment](continuous-deployment.md) then just change the configuration setting.
+Continuous delivery does not work well with GitFlow. The reason is that you are
+required to *merge* to master to do a release, triggering a rebuild and a new
+set of artifacts to go through your pipeline. Depending on how long your
+pipeline is, this could be a while.
+
+GitHubFlow is a better fit for Continuous delivery, the
+[mainline development](mainline-development.md) model means that every merged
+feature branch will be built as a *stable* version and if the build/builds go
+green then you are free to deploy to production at any time.
+
+## Usage
+By default, GitVersion is set up to do Continuous Delivery on all branches but
+`develop`, which is set up with [Continuous Deployment](continuous-deployment.md).
+To change the mode to Continuous Delivery, change your
+[configuration](../configuration.md) to:
+
+```yaml
+mode: ContinuousDelivery
+```
+
+## How Continuous Delivery affects GitVersion
+The thing about continuous delivery is that there will be *multiple* candidates
+to deploy to production and it is a human choice to deploy. This means that
+GitVersion will build **the same semantic version** until that version is
+deployed. For instance:
+
+ - 1.1.0+5
+ - 1.1.0+6
+ - 1.1.0+7  <-- This is the artifact we release, tag the commit which created
+   this version
+ - 1.1.1+0
+
+Tags are required in this mode to communicate when the release is done as it's
+an external manual process.
 
 ## Resources
  - [Continuous Delivery on Uncyclopedia](https://en.wikipedia.org/wiki/Continuous_delivery)
- - [Continuous Delivery, the book](http://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912)
+ - [Continuous Delivery, the book](http://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912)

docs/reference/continuous-delivery.md

@@ -1,6 +1,33 @@
 # Continuous Deployment
-Continuous deployment is the process of checking into master, running all the tests and if everything goes green it is automatically pushed to production.
+Continuous Deployment is the process of checking into master, running all the
+tests and if everything goes green it is automatically pushed to production.
 
-By default GitVersion is *not* setup to do this. The good news is in v3 of GitVersion this behavior is configurable!
+A good case for Continuous Deployment is when using Octopus deploy, as you
+cannot publish the same version of a package into the same feed.
 
-The default behavior for v3 and how v1 & 2 worked was that the version only incremented after a tag, which signified a release. In v3 you can simply switch the default mode in the [configuration](../configuration.md) from `continuous-delivery` to `continuous-deployment` and the version will then increment each commit, giving you the features of GitVersion with continuous deployment.
+For this mode we follow the logic in [this blog post by Xavier Decoster][blog]
+on the issues of incrementing automatically.
+
+As such we force a pre-release tag on all branches, this is fine for
+applications but can cause problems for libraries. As such this mode may or may
+not work for you, which leads us into a new mode in v4 of GitVersion:
+[Mainline Development](mainline-development.md).
+
+### Usage
+By default GitVersion is set up to do Continuous Deployment versioning on the
+`develop` branch, but for all other branches,
+[Continuous Delivery](continuous-delivery.md) is the default mode. From version
+3 of GitVersion this behavior is [configurable](../configuration.md).
+
+The default behavior for v3 and how v1 & 2 worked was that the version only
+incremented after a tag, which signified a release. In v3 you can simply switch
+the default mode in the [configuration](../configuration.md) from
+`ContinuousDelivery` to `ContinuousDeployment` and the version will then
+increment each commit, giving you the features of GitVersion with continuous
+deployment:
+
+```yaml
+mode: ContinuousDeployment
+```
+
+[blog]: http://www.xavierdecoster.com/semantic-versioning-auto-incremented-nuget-package-versions

docs/reference/continuous-deployment.md

@@ -1,6 +1,57 @@
 # Mainline development
-Mainline development is enabled when using [GitHubFlow](../git-branching-strategies/githubflow.md) or any other strategy where you develop on `master`. The main rule of mainline development is that **master is always in a state that it could be deployed to production**. This means that pull requests should not be merged until they are ready to go out.
+Mainline Development is enabled when using
+[GitHubFlow](../git-branching-strategies/githubflow.md) or any other strategy
+where you develop on `master`. The main rule of mainline development is that
+**master is always in a state that it could be deployed to production**. This
+means that pull requests should not be merged until they are ready to go out.
 
-To properly achieve mainline development you need confidence in your test suite as if it goes green against a PR then you are confident that you can merge and release that pull request. Another property of mainline development is normally that you fix going forward, not revert. When an issue is discovered with a release, add a test or some sort of check to make sure it won't happen again, fix the issue, then do a release with the fix.
+To properly achieve mainline development you need confidence in your test suite
+as if it goes green against a PR then you are confident that you can merge and
+release that pull request. Another property of mainline development is normally
+that you fix going forward, not revert. When an issue is discovered with a
+release, add a test or some sort of check to make sure it won't happen again,
+fix the issue, then do a release with the fix.
 
-Like all things, it is an approach and will work for some people and not for others. GitVersion is unique in the fact that it works very well with mainline development and the version numbers it generates are *predictive* and indicate what the next version to be released is. Most other approaches require bumping the version number before the release which means that the version being built and the version number which will be deployed are often different.
+Like all things, it is an approach and will work for some people and not for
+others. GitVersion is unique in the fact that it works very well with mainline
+development and the version numbers it generates are *predictive* and indicate
+what the next version to be released is. Most other approaches require bumping
+the version number before the release which means that the version being built
+and the version number which will be deployed are often different.
+
+This mode is great if you do not want to tag each release because you simply
+deploy every commit to master. The behaviour of this mode is as follows:
+
+1. Calclate a base version (likely a tag in this mode)
+2. Walk all commits from the base version commit
+3. When a merge commit is found:
+    - Calculate increments for each direct commit on master
+    - Calculate the increment for the branch
+4. Calculate increments for each remaining direct commit
+5. For feature branches then calculate increment for the commits so far on your
+   feature branch.
+
+If you *do not want* GitVersion to treat a commit or a pull request as a release
+and increment the version you can use `+semver: none` or `+semver: skip` in a
+commit message to skip incrementing for that commit.
+
+Here is an example of what mainline development looks like:
+
+![Mainline mode](../img/mainline-mode.png)
+
+**WARNING:** This approach can slow down over time, we recommend to tag
+intermitently (maybe for minor or major releases) because then GitVersion
+will start the version calculation from that point. Much like a snapshot in an
+event sourced system. We will probably add in warnings to tag when things are
+slowing down.
+
+## Usage
+By default GitVersion is set up to do [Continuous Delivery](continuous-delivery.md)
+versioning on all branches but `develop` (which does
+[Continuous Deployment](continuous-deployment.md) by default). To change the
+[versioning mode](versioning-mode.md) to Mainline Development, just
+change the [configuration](../configuration.md) as such:
+
+```yaml
+mode: Mainline
+```

docs/reference/mainline-development.md

@@ -0,0 +1,17 @@
+# Versioning modes
+GitVersion has multiple modes to fit different different ways of working.
+
+## Continuous Delivery
+[Continuous Delivery](/reference/continuous-delivery) is the default mode. In
+this mode, GitVersion calculates the next version and will use that until that
+is released.
+
+## Continuous Deployment
+Sometimes you just want the version to keep changing and deploy continuously.
+In this case, [Continuous Deployment](/reference/continuous-deployment) is a
+good mode to operate GitVersion by.
+
+## Mainline Development
+[Mainline Development](/reference/mainline-development) works more like the
+[Continuous Delivery](/reference/continuous-delivery), except that it tells
+GitVersion to *infer* releases from merges and commits to `master`.

docs/reference/versioning-mode.md

@@ -4,14 +4,14 @@ repo_url: https://github.com/GitTools/GitVersion
 
 pages:
 - Home: index.md
-- Usage: 
+- Usage:
   - Usage: usage/usage.md
   - Command Line: usage/command-line.md
   - MSBuild Task: usage/msbuild-task.md
   - NuGet Library: usage/nuget-library.md
   - Gem: usage/gem.md
 - Configuration: configuration.md
-- Build Server Support: 
+- Build Server Support:
     - Introduction: build-server-support/build-server-support.md
     - Build Servers:
       - AppVeyor: build-server-support/build-server/appveyor.md
@@ -45,12 +45,15 @@ pages:
   - GitHubFlow Examples: git-branching-strategies/githubflow-examples.md
   - Converting to GitFlow: git-branching-strategies/converting-to-gitflow.md
   - Creating/Updating examples: git-branching-strategies/creating-updating-examples.md
+  - Complete: git-branching-strategies/gitflow-examples_complete.md
 
 - Reference:
   - Intro to SemVer: reference/intro-to-semver.md
   - Git setup: reference/git-setup.md
   - Feature branches: reference/feature-branches.md
   - Pull requests: reference/pull-requests.md
-  - Mainline development: reference/mainline-development.md
-  - Continous delivery: reference/continuous-delivery.md
-  - Continuous deployment: reference/continuous-deployment.md
+  - Versioning modes:
+    - Versioning modes: reference/versioning-mode.md
+    - Mainline development: reference/mainline-development.md
+    - Continous delivery: reference/continuous-delivery.md
+    - Continuous deployment: reference/continuous-deployment.md

docs/versioning-mode.md

@@ -14,6 +14,14 @@
 [TestFixture]
 public class DocumentationTests
 {
+    private DirectoryInfo docsDirectory;
+
+    [OneTimeSetUp]
+    public void OneTimeSetUp()
+    {
+        docsDirectory = GetDocsDirectory();
+    }
+
     [Test]
     public void ConfigurationDocumentationIsUpToDate()
     {
@@ -32,7 +40,7 @@ public void ConfigurationDocumentationIsUpToDate()
 
         foreach (var configProperty in configProperties)
         {
-            var formattedConfigProperty = string.Format("**`{0}:`**", configProperty);
+            var formattedConfigProperty = string.Format("### {0}", configProperty);
             configurationDocumentationFile.ShouldContain(formattedConfigProperty,
                                                          Environment.NewLine + configurationDocumentationFile);
         }
@@ -54,8 +62,44 @@ public void VariableDocumentationIsUpToDate()
         }
     }
 
+    [Test]
+    public void DocumentationIndexIsUpToDate()
+    {
+        var documentationIndexFile = ReadDocumentationFile("../mkdocs.yml");
+        var docsDirectoryPath = new Uri(docsDirectory.FullName, UriKind.Absolute);
+
+        Console.WriteLine(docsDirectoryPath);
+
+        foreach (var markdownFile in docsDirectory.EnumerateFiles("*.md", SearchOption.AllDirectories))
+        {
+            var fullPath = new Uri(markdownFile.FullName, UriKind.Absolute);
+            var relativePath = docsDirectoryPath
+                .MakeRelativeUri(fullPath)
+                .ToString()
+                .Replace("docs/", string.Empty);
+
+            Console.WriteLine(fullPath);
+            Console.WriteLine(relativePath);
+
+            documentationIndexFile.ShouldContain(relativePath, () => string.Format("The file '{0}' is not listed in 'mkdocs.yml'.", relativePath));
+        }
+    }
+
+    private string ReadDocumentationFile(string relativeDocumentationFilePath)
+    {
+        var documentationFilePath = Path.Combine(docsDirectory.FullName, relativeDocumentationFilePath);
+        // Normalize path separators and such.
+        documentationFilePath = new FileInfo(documentationFilePath).FullName;
+
+        if (!File.Exists(documentationFilePath))
+        {
+            throw new FileNotFoundException(string.Format("The documentation file '{0}' couldn't be found.", documentationFilePath), documentationFilePath);
+        }
 
-    static string ReadDocumentationFile(string relativeDocumentationFilePath)
+        return File.ReadAllText(documentationFilePath);
+    }
+
+    private static DirectoryInfo GetDocsDirectory()
     {
         var currentDirectory = new FileInfo(typeof(DocumentationTests).Assembly.Location).Directory;
         while (currentDirectory != null)
@@ -78,15 +122,6 @@ static string ReadDocumentationFile(string relativeDocumentationFilePath)
             throw new DirectoryNotFoundException("Couldn't find the 'docs' directory.");
         }
 
-        var documentationFilePath = Path.Combine(currentDirectory.FullName, relativeDocumentationFilePath);
-        // Normalize path separators and such.
-        documentationFilePath = new FileInfo(documentationFilePath).FullName;
-
-        if (!File.Exists(documentationFilePath))
-        {
-            throw new FileNotFoundException(string.Format("The documentation file '{0}' couldn't be found.", documentationFilePath), documentationFilePath);
-        }
-
-        return File.ReadAllText(documentationFilePath);
+        return currentDirectory;
     }
 }