Merge pull request #502 from JakeGinnivan/DocsUpdate

Docs update

Author: JakeGinnivan

BREAKING CHANGES.md

@@ -1,6 +1,5 @@
 v3.0.0
- - Develop no longer tracks master
- - NextVersion.txt has been deprecated, only GitVersion.yaml is supported
+ - NextVersion.txt has been deprecated, only GitVersionConfig.yaml is supported
  - `AssemblyFileSemVer` variable removed, AssemblyVersioningScheme configuration value makes this variable obsolete
  - Variables `ClassicVersion` and `ClassicVersionWithTag` removed
  - MSBuild task arguments (AssemblyVersioningScheme, DevelopBranchTag, ReleaseBranchTag, TagPrefix, NextVersion) have been removed, use GitVersionConfig.yaml instead

CONTRIBUTING.md

@@ -6,18 +6,23 @@ We love contributions to get started contributing you might need:
  - [An issue to work on](https://github.com/ParticularLabs/GitVersion/labels/up-for-grabs) - We are on [Up for grabs](http://up-for-grabs.net/), our up for grabs issues are tagged `up-for-grabs`
  - An understanding of our [architecture](#architecture) and how [we write tests](#writing-tests)
 
-Once you know how to create a pull request and have an issue to work on, just post a comment saying you will work on it. 
+Once you know how to create a pull request and have an issue to work on, just post a comment saying you will work on it.
 If you end up not being able to complete the task, please post another comment so others can pick it up.
 
-Issues are also welcome, [failing tests](#writing-tests) are even more welcome. 
+Issues are also welcome, [failing tests](#writing-tests) are even more welcome.
+
+# Contribution Guidelines
+ - Try to use feature branches rather than developing on master
+ - Please include tests covering the change
+ - The docs are now stored in the repository under the `Docs` folder, please include documentation updates with your PR
 
 # 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. 
+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. 
+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)
@@ -46,7 +51,7 @@ Each strategy needs to return an instance of `BaseVersion` which has the followi
    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
 
 # Writing Tests
-We have made it super easy to write tests in GitVersion. Most tests you are interested in are in `GitVersionCore.Tests\IntegrationTests`. 
+We have made it super easy to write tests in GitVersion. Most tests you are interested in are in `GitVersionCore.Tests\IntegrationTests`.
 
 There is a scenario class for each type of branch. For example MasterScenarios, FeatureBranchScenarios etc.
 
@@ -57,7 +62,7 @@ Find where your issue would logically sit. Or create a new scenario class if it
 We are currently using NUnit, so just create a descriptive test method and attribute it with `[Test]`
 
 ## 3. Use a fixture
-We have a few fixtures for different scenarios. 
+We have a few fixtures for different scenarios.
 
  - `EmptyRepositoryFixture` - Gives you an empty git repo to start with
  - `RemoteRepositoryFixture` - A local repo tracking a test remote repository. The remote repo is available through the `Repository` property, the local is accessible via `LocalRepository`
@@ -90,4 +95,4 @@ fixture.AssertFullSemver("1.0.1-test.1+5");
 The last line is the most important. `AssertFullSemver` will run GitVersion and assert that the full SemVer it calculates is what you expect.
 
 ## 6. Submit a pull request with the failing test
-Even better include the fix, but a failing test is a great start
+Even better include the fix, but a failing test is a great start

Docs/branchingStrategies/gitFlow.md

@@ -0,0 +1,134 @@
+#GitFlow
+GitFlow allows more structured releases, and GitVersion will derive sensible SemVer compatible versions from this structure.
+
+### Assumptions:
+
+* Using [GitFlow branching model](http://nvie.com/git-model/) which always has a master and a develop branch
+* Following [Semantic Versioning](http://semver.org/)
+* Planned releases (bumps in major or minor) are done on release branches prefixed with release-. Eg: release-4.1 (or release-4.1.0)
+* Hotfixes are prefixed with hotfix- Eg. hotfix-4.0.4
+* The original GitFlow model (http://nvie.com/posts/a-successful-git-branching-model/) specifies branches with a "-" separator while the git flow extensions (https://github.com/nvie/gitflow) default to a "/" separator.  Either work with GitVersion.
+* Tags are used on the master branch and reflects the SemVer of each stable release eg 3.3.8 , 4.0.0, etc
+* Tags can also be used to override versions while we transition repositories over to GitVersion
+* Using a build server with multi-branch building enabled eg TeamCity 8
+
+### How Branches are handled
+
+The descriptions of how commits and branches are versioned can be considered a type of pseudopod. With that in mind there are a few common "variables" that we will refer to:
+
+* `targetBranch` => the branch we are targeting
+* `targetCommit` => the commit we are targeting on `targetbranch`
+
+#### Master branch
+
+Commits on master will always be a merge commit (Either from a `hotfix` or a `release` branch) or a tag. As such we can simply take the commit message or tag message.
+
+If we try to build from a commit that is no merge and no tag then assume `0.1.0`
+
+`mergeVersion` => the SemVer extracted from `targetCommit.Message`  
+
+* major: `mergeVersion.Major`
+* minor: `mergeVersion.Minor`
+* patch: `mergeVersion.Patch`
+* pre-release: 0 (perhaps count ahead commits later)
+* stability: final
+
+Optional Tags (only when transitioning existing repository):
+* TagOnHeadCommit.Name={semver} => overrides the version to be {semver}
+
+Long version:  
+
+    {major}.{minor}.{patch} Sha:'{sha}'
+    1.2.3 Sha:'a682956dccae752aa24597a0f5cd939f93614509'
+
+#### Develop branch
+
+`targetCommitDate` => the date of the `targetCommit`
+`masterVersionCommit` => the first version (merge commit or SemVer tag) on `master` that is older than the `targetCommitDate`
+`masterMergeVersion` => the SemVer extracted from `masterVersionCommit.Message`  
+
+* major: `masterMergeVersion.Major`
+* minor: `masterMergeVersion.Minor + 1` (0 if the override above is used)
+* patch: 0
+* pre-release: `unstable{n}` where n = how many commits `develop` is in front of `masterVersionCommit.Date` ('0' padded to 4 characters)
+
+Long version:  
+
+    {major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
+    1.2.3-unstable645 Branch:'develop' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
+
+#### Hotfix branches
+
+Named: `hotfix-{versionNumber}` eg `hotfix-1.2`
+
+`branchVersion` => the SemVer extracted from `targetBranch.Name`  
+
+* major: `mergeVersion.Major`
+* minor: `mergeVersion.Minor`
+* patch: `mergeVersion.Patch`
+* pre-release: `beta{n}` where n = number of commits on branch  ('0' padded to 4 characters)
+
+Long version:  
+
+    {major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
+    1.2.3-beta645 Branch:'hotfix-foo' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
+
+#### Release branches
+
+ * May branch off from: develop
+ * Must merge back into: develop and master
+ * Branch naming convention: `release-{n}` eg `release-1.2`
+
+`releaseVersion` => the SemVer extracted from `targetBranch.Name`
+`releaseTag` => the first version tag placed on the branch. Note that at least one version tag is required on the branch. The recommended initial tag is `{releaseVersion}.0-alpha1`. So for a branch named `release-1.2` the recommended tag would be `1.2.0-alpha1`
+
+* major: `mergeVersion.Major`
+* minor: `mergeVersion.Minor`
+* patch: 0
+* pre-release: `{releaseTag.preRelease}.{n}` where n = 1 + the number of commits since `releaseTag`.
+
+So on a branch named `release-1.2` with a tag `1.2.0-alpha1` and 4 commits after that tag the version would be `1.2.0-alpha1.4`
+
+Long version:  
+
+    {major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
+    1.2.3-alpha2.4 Branch:'release-1.2' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
+    1.2.3-rc2 Branch:'release-1.2' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
+
+#### Feature  branches
+
+May branch off from: `develop`
+Must merge back into: `develop`
+Branch naming convention: anything except `master`, `develop`, `release-{n}`, or `hotfix-{n}`.
+
+TODO: feature branches cannot start with a SemVer. to stop people from create branches named like "4.0.3"
+
+* major: `masterMergeVersion.Major`
+* minor: `masterMergeVersion.Minor + 1` (0 if the override above is used)
+* patch: 0
+* pre-release: `unstable.feature-{n}` where n = First 8 characters of the commit SHA of the first commit
+
+
+Long version:  
+
+    {major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
+    1.2.3-unstable.feature-a682956d Branch:'feature1' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
+
+#### Pull-request  branches
+
+May branch off from: `develop`
+Must merge back into: `develop`
+Branch naming convention: anything except `master`, `develop`, `release-{n}`, or `hotfix-{n}`. Canonical branch name contains `/pull/`.
+
+* major: `masterMergeVersion.Major`
+* minor: `masterMergeVersion.Minor + 1` (0 if the override above is used)
+* patch: 0
+* pre-release: `unstable.pull{n}` where n = the pull request number  ('0' padded to 4 characters)
+
+### Nightly Builds
+
+**develop**, **feature** and **pull-request** builds are considered nightly builds and as such are not in strict adherence to SemVer.
+
+## Release Candidates
+
+How do we do release candidates?? Perhaps  tag a release branch and then count commits forward from the tag to get RC1, RC2 etc??

Docs/branchingStrategies/readme.md

@@ -0,0 +1 @@
+This folder contains notes about different branching strategies and how they work in GitVersion

Docs/buildServerSetup/appVeyor.md

@@ -0,0 +1,7 @@
+# AppVeyor Setup
+AppVeyor is the first build server which has a setup helper built into `GitVersion init`.
+
+ 1. Run `GitVersion init`
+ 2. Choose `Setup build scripts` (currently option 7, but that could change)
+ 3. Choose `AppVeyor`
+ 4. Follow the prompts to generate an appveyor.yml file which works nicely with GitVersion

Docs/buildServerSetup/dynamicRepositories.md

@@ -0,0 +1,37 @@
+# Dynamic repositories
+GitVersion.exe requires access to the Git repository in order to do / infer all the lovely things that it does.
+
+Well maybe that's not so much of a revelation..
+
+_But did you know_ that in some circumstances, you may find that when your code is built, the build process isn't aware of the Git repository at all - i.e _there is no Git Repository available locally to the build!_
+
+For an example of one such circumstance, you can have a read about [Team City's checkout mode: Automatically on Server](https://confluence.jetbrains.com/display/TCD7/VCS+Checkout+Mode)
+
+So `how is GitVersion meant to work in that scenario?` - well it needs to be able to obtain a copy of the Git repo on the fly and not rely on the build system making one locally available..
+
+Enter: **Dynamically Obtained Repo's**
+
+## Tell GitVersion.exe how to obtain your repository
+
+Unless you tell GitVersion.exe how to obtain the Git repository, it will assume that the Git repository is already available locally to the process - i.e. it will assume there is already a ".git" folder present, and it will use it.
+
+To tell GitVersion.exe to obtain the repository on the fly, you need to call `GitVersion.exe` with the following arguments:
+
+* /url [the url of your git repo]
+* /u [authentication username]
+* /p [authentication password]
+* /b [branch name]
+* /c [commit id]
+
+Please note that these arguments (and their usage) are described [here.](https://github.com/ParticularLabs/GitVersion/wiki/Command-Line-Tool)
+
+Also, be aware that if you don't specify the `/b` argument (branch name) then GitVersion will currently fallback to targeting whatever the default branch name happens to be for the repo. This could lead to incorrect results, so for that reason it's recommended to always explicitly specify the branch name.
+
+NB: In Team City, the VCS branch is available from a configuration parameter with the following name:
+
+`teamcity.build.vcs.branch.<VCS root ID>`
+
+Where `<VCS root ID>` is the `VCS root ID` as described on the Configuring `VCS Roots` page.
+
+## Where is the repository stored
+GitVersion will checkout the dynamic repository into the %tmp% directory and just keep that dynamic repository up to date, this saves recloning the repository every build.

Docs/buildServerSetup/teamCity.md

@@ -0,0 +1,60 @@
+# TeamCity Setup
+## Basic Usage
+In [TeamCity](https://www.jetbrains.com/teamcity/) you can create a build step as follows:
+
+* **Runner type:** Command Line
+* **Run:** Executable with parameters
+* **Command executable:**  `GitVersion.exe`
+* **Command parameters:** `/output buildserver /updateassemblyinfo true`
+
+Then in your build parameters simply [add a placeholder](https://github.com/Particular/GitVersion/wiki/Variables#recommended-teamcity-setup) of the GitVersion variables you would like to use.
+
+GitVersion writes system parameters into TeamCity, so they will automatically be passed to your build scripts to use.
+
+## Running inside TeamCity
+* Make sure to use **agent checkouts** (required, server checkouts do not copy the needed `.git` directory)
+  - If you want to use *checkout on server*, see [dynamic repositories](dynamicRepositories.md)
+* For the moment you need to promote the `%teamcity.build.vcs.branch.{configurationid}%` build parameter to an environment variable with the same name for pull requests to be handled correctly
+* We update the TC build number to the GitVersion number automatically
+* We output the individual values of the GitVersion version as the build parameter: `GitVersion.*` (Eg: `GitVersion.Major`) if you need access to them in your build script
+
+### NuGet in TeamCity
+* Add dummy [parameter](http://confluence.jetbrains.com/display/TCD8/Configuring+Build+Parameters) to
+the project called `GitVersion.NuGetVersion`. If many of your projects uses git-flow and SemVer you
+can add the parameter to the "root-project" (TeamCity 8.x+)
+* Then setup you nuget pack build set the "version" to `%GitVersion.NuGetVersion%`
+
+### When TeamCity -> GitHub can't use https
+GitVersion requires the presence of master branch in order to determine the version number.  If TeamCity uses https to clone git repos then GitVersion will pull down master branch for you during the build.
+
+If however your TeamCity uses SSH to clone git repos and https is unavailable then GitVersion will error with a message like
+
+> [GitVersionTask.UpdateAssemblyInfo] Error occurred: GitVersion.MissingBranchException: Could not fetch from 'git@github.dev.xero.com:Xero/Bus.git' since LibGit2 does not support the transport. You have most likely cloned using SSH. If there is a remote branch named 'master' then fetch it manually, otherwise please create a local branch named 'master'. ---> LibGit2Sharp.LibGit2SharpException: An error was raised by libgit2. Category = Net (Error).
+This transport isn't implemented. Sorry
+
+You need to create a TeamCity build step before your compile step which manually creates a local master branch which tracks remote master.  Like so (in powershell):
+
+```Powershell
+$branchBeingBuilt = . git symbolic-ref --short -q HEAD  
+. git pull 2>&1 | write-host
+foreach ($remoteBranch in . git branch -r) {
+  . git checkout $remoteBranch.Trim().Replace("origin/", "") 2>&1 | write-host
+  . git pull 2>&1 | write-host  
+}  
+. git checkout $branchBeingBuilt 2>&1 | write-host  
+exit 0
+```
+
+you should get build output like
+
+```
+[Step 1/1]: Ensure all branches are available for GitVersion (Powershell) (5s)
+[Step 1/1] From file:///C:/BuildAgent2/system/git/git-12345678
+[Step 1/1]  * [new branch]      master     -> origin/master
+[Step 1/1] Switched to a new branch 'master'
+[Step 1/1] Branch master set up to track remote branch master from origin.
+[Step 1/1] Switched to branch 'develop'
+```
+
+## Guides
+ - [Continuous Delivery Setup in TeamCity](http://jake.ginnivan.net/blog/2014/07/09/my-typical-teamcity-build-setup)

Docs/buildServers.md

@@ -0,0 +1,31 @@
+# Build Server Support
+GitVersion has support for quite a few build servers out of the box. Currently we support:
+
+ - TeamCity
+ - AppVeyor
+ - Continua Ci
+ - MyGet
+
+When GitVersion.exe is run with the `/output buildserver` flag instead of outputting Json it will export variables to the current build server.
+For instance if you are running in TeamCity after you run `GitVersion /output buildserver` you will have the `%system.GitVersion.SemVer%` available for you to use
+
+When running in MSBuild either from the MSBuild Task or by using the `/proj myproject.sln` GitVersion will make the MSBuild variables available in the format `$(GitVersion_SemVer)`.
+
+## Setup guides
+ - [AppVeyor](buildServerSetup/appVeyor.md)
+ - [TeamCity](buildServerSetup/teamCity.md)
+
+## Other plugins/helpers
+### GitVersion meta runner for TeamCity
+TeamCity has support for meta-runners which allow custom tasks. There is a GitVersion meta-runner available which makes it easy to use GitVersion.
+
+ - [Project Link](https://github.com/JetBrains/meta-runner-power-pack/tree/master/gitversion)
+
+### GitVersion for Bamboo
+If you use Bamboo then you can install *GitVersion for Bamboo* which gives you a GitVersion task in Bamboo.
+
+ - [Blog Post](http://carolynvanslyck.com/blog/2015/03/gitversion-for-bamboo)
+ - [Project link](http://carolynvanslyck.com/projects/gitversion)
+ - [Download](https://marketplace.atlassian.com/plugins/com.carolynvs.gitversion)
+ - [Source](http://carolynvanslyck.com/projects/gitversion)
+ - [Issues](http://jira.carolynvanslyck.com/browse/GITVER)