Merge pull request #524 from JakeGinnivan/FinishingOffMissingDocs

Finishing off missing docs

Author: JakeGinnivan

docs/git-branching-strategies/gitflow-examples.md

@@ -1,9 +1,16 @@
 # GitFlow Examples
+These examples are using the *default* configuration with GitVersion. Which is [continuous deployment](../reference/continuous-deployment.md) mode for `develop` and [continuous delivery](../reference/continuous-delivery.md) mode for all other branches.
+
+This default configuration allows you to publish CI builds from develop to a CI MyGet feed, or another CI feed. Then all other branches are manually released then tagged. Read more about this at [version increments](../more-info/version-increments.md).
+
 ## Feature Branches
 Feature branches will take the feature branch name and use that as the pre-release tag.
 
 ![GitFlow](img/05119d0cd4ecaaefff94_feature-branch.png)
 
+Notice after the feature branch is merged, the version on `develop` is `1.3.0-unstable.3`. This is due to `develop` running in *continuous deployment* mode. If you configured `develop` to use *continuous delivery* the version would still be `1.3.0-unstable.1` and you would have to use release tags to increment the `unstable.1`.
+
+You can see the different on the feature branch itself, notice the version is the same before and after the commit on the feature branch? Only the metadata has changed. If you released the feature branch artifacts then tagged the commit, the following commit would increase to `-beta.2`.
 
 ## Pull Request
 Because feature branches are most likely pushed to a fork, we are showing the

docs/git-branching-strategies/githubflow-examples.md

@@ -1,6 +1,12 @@
 # GitHubFlow Examples
-## Continuous Delivery mode
-TODO Example of GitHubFlow using continuous delivery mode
 
-## Continuous Deployment mode
-TODO Example of GitHubFlow using continuous deployment mode
+## Feature branch
+![GitHubFlow](img/githubflow_feature-branch.png)
+
+## Pull requests
+![GitHubFlow](img/githubflow_pull-request.png)
+
+## Release branch
+Release branches can be used in GitHubFlow as well as GitFlow. Sometimes you want to start on a large feature which may take a while to stabilise so you want to keep it off master. In these scenarios you can either create a long lived feature branch (if you do not know the version number this large feature will go into, and it's non-breaking) otherwise you can create a release branch for the next major version. You can then submit pull requests to the long lived feature branch or the release branch.
+
+![GitFlow](img/githubflow_release-branch.png)

docs/git-branching-strategies/githubflow.md

@@ -15,3 +15,5 @@ The main rule of GitHub Flow is that master should *always* be deployable. GitHu
 ## Resources
  - [GitHubFlow guide by GitHub](https://guides.github.com/introduction/flow/index.html)
  - [GitHub Flow original blog post](http://scottchacon.com/2011/08/31/github-flow.html)
+ - [Phil Haack's (haacked) GitHubFlow aliases](http://haacked.com/archive/2014/07/28/github-flow-aliases/)
+ - [GitHubFlow vs GitFlow](http://lucamezzalira.com/2014/03/10/git-flow-vs-github-flow/)

docs/git-branching-strategies/img/githubflow_feature-branch.png

@@ -0,0 +1,27 @@
+# Octopus deploy
+While not a build server, there are a few things to consider when using Octopus Deploy with GitVersion.
+
+ - GitVersion follows [continuous delivery](../../reference/continuous-delivery.md) versioning by default
+   - This means builds will keep producing *the same version* with just metadata differing.
+     If you try to push every build into Octopus you will have issues
+
+Because Octopus uses NuGet under the covers you cannot publish every build into Octopus deploy. For this we have two possible options:
+
+## Solutions
+### 'Release' packages to Octopus deploy
+Rather than all builds going into Octopus's NuGet feed, you release builds into it's feed. When you push a package into the NuGet feed you need to tag that release. The next commit will then increment the version.
+This has the advantage that if you have a multi-stage deployment pipeline you pick packages which you would like to start through the pipeline, then you can see all the versions which did not make it through the pipeline (for instance, they got to UAT but not production due to a bug being found). In the release notes this can be mentioned or those versions can be skipped.
+
+The steps for this would be
+
+1. Build server has a release build
+  - The release build publishes the built NuGet package into a NuGet feed which Octopus deploy consumes
+2. The release build should then automatically trigger the first stage of deployments.
+  - This could be into a test/uat environment. You can then use Octopus to promote that version through the different environments.
+  - You could also do this manually, but if you are triggering a release build you are indicating that is a candidate which you want deployed
+3. Tag the source commit with the version. This will cause GitVersion to start building the next version
+
+This approach works well with Semantic Versioning, as you will not be burning version numbers between releases (except if a build fails to get through UAT or something, then the burnt number means something!).
+
+### Configure GitVersion to [increment per commit](../incrementing-per-commit.md)
+As mentioned above, this means you will burn multiple versions per release. This might not be an issue for you, but can confuse consumers of your library as the version has semantic meaning.

docs/git-branching-strategies/img/githubflow_pull-request.png

@@ -1,2 +1,38 @@
 # How it works
-coming soon...
+GitVersion v3 works very differently to v2. Version 2 had knowledge of both GitFlow and GitHubFlow hard coded into it, with each branch having it's own class which calculated the version for that branch type.
+
+v3 is driven by [configuration](../configuration.md), meaning most of the behaviors in GitVersion can be tweaked to work the way you want. It also makes it *much* more predictable and easy to diagnose why odd things are happening. 
+
+## Architecture
+GitVersion has three distict steps for calculating versions in v3.0.
+
+1. If the current commit is tagged, the tag is used and build metadata (Excluding commit count) is added. The other two steps will not execute
+2. A set of strategies are evaluated to decide on the base version and some metadata about that version.
+   These strategies include HighestReachableTag, NextVersionInConfig, MergedBranchWithVersion, VersionInBranchName etc.
+3. The highest base version is selected, using that base version the new version is calculated.
+
+Visually it looks something like this:
+![Version Calculation](http://www.plantuml.com:80/plantuml/png/fLCxJyCm4DxzAsuib4P914i69De1CS38Vd6kYIN7ZcodK8aVp-KX6Y2fKCbY9NV-7lVb2WoOeoVOMRDNfH0lz1vUoNbbpGwrR3K6ws1p3rlk-bN8u972f2AC3GHEbLN8m1D1Jjg-mPuXAZvx9kL1ZW1KY5dOZczMI0Pf54VnHtf7jpaAWJg0sW-uXw4PK3Eb1sMaevfCW6i1_0m6po1l7HfPJUxvu5XYUOHLWq5MLptCudmMK9--u5glJ0dIEaVo1Dw3JgVM6Km4cM9mzyrQXHuQHnj7chhl0JcnIrHjno1wiWtgfi8eWVK_7OQAmBHrJWvORFVM2PmrE7AcWZGh-Lj0FvptVvLiUPnCdG_XhNhOov9wQ1fzv7nw5S5EwSvw6CDQNfnMwUAP0XQyQpj70nkx3Nn3p5NFY9IshbNWepKi8ublWFiSPkC0ee8El75Dv5aOxqZQBScbWpWn0Pe2wb6aM1p4Eea_0G00)
+
+[Edit Diagram](http://www.plantuml.com/plantuml/form?url=http://www.plantuml.com/plantuml/png/fLCxJyCm4DxzAsuib4P914i69De1CS38Vd6kYIN7ZcodK8aVp-KX6Y2fKCbY9NV-7lVb2WoOeoVOMRDNfH0lz1vUoNbbpGwrR3K6ws1p3rlk-bN8u972f2AC3GHEbLN8m1D1Jjg-mPuXAZvx9kL1ZW1KY5dOZczMI0Pf54VnHtf7jpaAWJg0sW-uXw4PK3Eb1sMaevfCW6i1_0m6po1l7HfPJUxvu5XYUOHLWq5MLptCudmMK9--u5glJ0dIEaVo1Dw3JgVM6Km4cM9mzyrQXHuQHnj7chhl0JcnIrHjno1wiWtgfi8eWVK_7OQAmBHrJWvORFVM2PmrE7AcWZGh-Lj0FvptVvLiUPnCdG_XhNhOov9wQ1fzv7nw5S5EwSvw6CDQNfnMwUAP0XQyQpj70nkx3Nn3p5NFY9IshbNWepKi8ublWFiSPkC0ee8El75Dv5aOxqZQBScbWpWn0Pe2wb6aM1p4Eea_0G00)
+
+**\*** Some strategies allow the version to be incremented, others don't. More info below  
+**+** This version is out of context with the rest of the example. It is here just to show what happens if the check is true
+
+### Base Version Strategies
+Currently we have the following strategies
+
+ - `HighestTagBaseVersionStrategy` - Finds the highest reachable tag from the current branch
+ - `VersionInBranchBaseVersionStrategy` - Extracts version information from the branch name. eg `release/3.0.0` will find `3.0.0`
+ - `ConfigNextVersionBaseVersionStrategy` - Returns the version from the GitVersion.yaml file
+ - `MergeMessageBaseVersionStrategy` - Finds version numbers from merge messages. eg. `Merge 'release/3.0.0' into 'master'` will return `3.0.0`
+ - `FallbackBaseVersionStrategy` - Always returns 0.1.0 for new repositories
+
+Each strategy needs to return an instance of `BaseVersion` which has the following properties
+
+ - `Source` - Description of the source. eg `Merge message 'Merge 'release/3.0.0' into 'master''
+ - `ShouldIncrement` - Some strategies should have the version incremented, others do not. eg `ConfigNextVersionBaseVersionStrategy` returns false, `HighestTagBaseVersionStrategy` returns true
+ - `SemanticVersion` - SemVer of the base version strategy
+ - `BaseVersionSource` - Sha of the source. Commits will be counted from this Sha. Can be null (eg ConfigNextVersionBaseVersionStrategy returns null)
+ - `BranchNameOverride` - When `useBranchNameAsTag` is used, this allows the branch name to be changed by a base version.  
+   VersionInBranchBaseVersionStrategy uses this to strip out anything before the first - or /. So `foo` ends up being evaluated as `foo`. If in doubt, just use null

docs/git-branching-strategies/img/githubflow_release-branch.png

@@ -17,14 +17,7 @@ If you are using GitFlow then builds off the `develop` branch will actually *inc
 If you need to consume packages built from develop, we recommend publishing these packages to a separate NuGet feed as an alpha channel. That way you can publish beta/release candidate builds and only people who opt into the alpha feed will see the unstable pacakges.
 
 ### 2. Octopus deploy
-Because Octopus uses NuGet under the covers you cannot publish every build into Octopus deploy. For this we have two possible options:
-
-#### 2a. 'Release' packages to Octopus deploy
-Rather than all builds going into Octopus's NuGet feed, you release builds into it's feed. When you push a package into the NuGet feed you need to tag that release. The next commit will then increment the version.
-This has the advantage that if you have a multi-stage deployment pipeline you pick packages which you would like to start through the pipeline, then you can see all the versions which did not make it through the pipeline (for instance, they got to UAT but not production due to a bug being found). In the release notes this can be mentioned or those versions can be skipped.
-
-#### 2b. Configure GitVersion to increment per commit
-As mentioned above, this means you will burn multiple versions per release. This might not be an issue for you, but can confuse consumers of your library as the version has semantic meaning.
+See [Octopus deploy](build-server-setup/octopus-deploy.md)
 
 ## Manually incrementing the version
 With v3 there are multiple approaches.

docs/more-info/build-server-setup/octopus-deploy.md

@@ -0,0 +1,26 @@
+# 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.
+
+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 the build is green, the application can be deployed at any time
+   - Ideally the buisiness 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.
+
+## Resources
+ - [Continuous Delivery on Wikipedia](https://en.wikipedia.org/wiki/Continuous_delivery)
+ - [Continuous Delivery, the book](http://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912)