Merge pull request #516 from JakeGinnivan/MoreDocImprovements

[WIP] More doc improvements

Author: JakeGinnivan

Docs/branchingStrategies/convertingToGitFlow.md

@@ -0,0 +1,10 @@
+# Converting to GitFlow
+Converting to GitFlow is simple. Whenever you need to convert, simply do the following
+
+```
+git checkout master
+git checkout -b develop
+git push upstream develop
+```
+
+Then in GitHub go to your repository settings then set develop to be your default branch. And now all development happens on the `develop` branch

Docs/branchingStrategies/gitFlow.md

@@ -1,7 +1,9 @@
 #GitFlow
 GitFlow allows more structured releases, and GitVersion will derive sensible SemVer compatible versions from this structure.
 
-### Assumptions:
+## Resources
+
+## 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/)
@@ -12,14 +14,14 @@ GitFlow allows more structured releases, and GitVersion will derive sensible Sem
 * 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
+## 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
+### 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.
 
@@ -41,7 +43,7 @@ Long version:
     {major}.{minor}.{patch} Sha:'{sha}'
     1.2.3 Sha:'a682956dccae752aa24597a0f5cd939f93614509'
 
-#### Develop branch
+### 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`
@@ -57,7 +59,7 @@ Long version:
     {major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
     1.2.3-unstable645 Branch:'develop' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
 
-#### Hotfix branches
+### Hotfix branches
 
 Named: `hotfix-{versionNumber}` eg `hotfix-1.2`
 
@@ -73,7 +75,7 @@ Long version:
     {major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
     1.2.3-beta645 Branch:'hotfix-foo' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
 
-#### Release branches
+### Release branches
 
  * May branch off from: develop
  * Must merge back into: develop and master
@@ -95,7 +97,7 @@ Long version:
     1.2.3-alpha2.4 Branch:'release-1.2' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
     1.2.3-rc2 Branch:'release-1.2' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
 
-#### Feature  branches
+### Feature branches
 
 May branch off from: `develop`
 Must merge back into: `develop`
@@ -114,7 +116,7 @@ Long version:
     {major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
     1.2.3-unstable.feature-a682956d Branch:'feature1' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
 
-#### Pull-request  branches
+### Pull-request branches
 
 May branch off from: `develop`
 Must merge back into: `develop`
@@ -125,7 +127,7 @@ Branch naming convention: anything except `master`, `develop`, `release-{n}`, or
 * patch: 0
 * pre-release: `unstable.pull{n}` where n = the pull request number  ('0' padded to 4 characters)
 
-### Nightly Builds
+## Nightly Builds
 
 **develop**, **feature** and **pull-request** builds are considered nightly builds and as such are not in strict adherence to SemVer.
 

Docs/branchingStrategies/gitFlowExamples.md

@@ -0,0 +1,6 @@
+# GitFlow Examples
+## Continuous Delivery mode
+TODO Example of GitFlow using continuous delivery mode
+
+## Continuous Deployment mode
+TODO Example of GitFlow using continuous deployment mode

Docs/branchingStrategies/gitHubFlow.md

@@ -0,0 +1,17 @@
+# GitHub Flow
+GitHub Flow is a simple and effective branching strategy which the folks at GitHub use. Most teams actually do not need everything GitFlow gives them and are much better off with a simpler workflow.
+
+GitHub Flow is in a nutshell:
+
+1) Update master to latest [upstream](../Reference/gitSetup.md#upstream) code
+2) Create a feature branch `git checkout -b myFeatureBranch`
+3) Do the feature/work
+4) Push feature branch to [origin](../Reference/gitSetup.md#origin)
+5) Create pull request from origin/<featureBranch> -> upstream/master
+6) Review, fix raised comments, merge your PR or even better, get someone else to.
+
+The main rule of GitHub Flow is that master should *always* be deployable. GitHub Flow allows and encourages [continuous deliver](../Reference/Continuous-Delivery.md).
+
+## 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)

Docs/branchingStrategies/gitHubFlowExamples.md

@@ -0,0 +1,6 @@
+# GitHubFlow Examples
+## Continuous Delivery mode
+TODO Example of GitHubFlow using continuous delivery mode
+
+## Continuous Deployment mode
+TODO Example of GitHubFlow using continuous deployment mode

Docs/branchingStrategies/img/gitflow_1.png

@@ -1 +1,35 @@
-This folder contains notes about different branching strategies and how they work in GitVersion
+# Branching strategies
+There are two mainstream branching strategies in git and many lesser known strategies.
+
+When building GitVersion we had to work through not only how to use the branching strategies but how we could fully support semantic versioning in each of these strategies.
+
+## Introduction to branching strategies
+Git is a very powerful tool and if you do not settle on a branching strategy and associated workflows then you will likely lose work at some point. At the start of any project I recommend picking a branching strategy and making sure your whole team understands it.
+
+As mentioned above the GitVersion docs cover GitHubFlow and GitFlow.
+
+### GitHubFlow
+GitHubFlow is a simple and powerful branching strategy. It is what GitHub uses and the branching strategy most open source projects use.
+
+ - [Mainline development](../Reference/mainline-development.md) on `master`
+ - Work on [feature branches](../Reference/featureBranches.md), merge into `master` via [pull requests](../Reference/pull-requests.md)
+ - Works well for [continuous delivery](../Reference/Continuous-Delivery.md)
+ - Does not have a way to manage/maintain old releases
+ - Only allows working on a single release at a time
+
+### GitFlow
+GitFlow is a more complex and complete branching strategy. It also gives much more control over when features and code is released.
+
+ - Development on `develop` branch
+ - `master` only contains *released* code
+ - Supports maintaining old releases (like nServiceBus, they support the last 3 major versions with bug fixes and security updates)
+ - Supports development on multiple releases at one time
+
+## Choosing a branching strategy
+There are a few reasons you would pick GitFlow over GitHubFlow, they are:
+
+1) You need to support multiple major versions at the same time
+2) You need to work on multiple releases at the same time
+ - For example a new feature which will go in the next major version, while bug fixes/smaller features are still going into the current release
+
+But if you do not have a good reason to go with GitFlow, then start with GitHubFlow. It is a far simpler model and if you end up needing GitFlow later, it is [easy to convert](convertingToGitFlow.md)

Docs/branchingStrategies/readme.md

@@ -12,7 +12,7 @@ For instance if you are running in TeamCity after you run `GitVersion /output bu
 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)
+ - [AppVeyor](buildServerSetup/AppVeyor.md)
  - [TeamCity](buildServerSetup/teamCity.md)
 
 ## Other plugins/helpers

Docs/buildServers.md

@@ -17,8 +17,8 @@ The configuration options are:
 
  - `next-version`: Allows you to bump the next version explicitly, useful for bumping `master` or a feature with breaking changes a major increment.
  - `assembly-versioning-scheme`: When updating assembly info tells GitVersion how to treat the AssemblyVersion attribute. Useful to lock the major when using Strong Naming.
- - `mode`: Either ContinuousDelivery or ContinuousDeployment. See [Octopus Deploy/CI Build NuGet Packages](#continuousdeployment) above for more information
- - `continuous-delivery-fallback-tag`: When using `mode: ContinuousDeployment` the value specified will be used as the pre-release tag for branches which do not have one specified.
+ - `mode`: Either Continuous-Delivery or ContinuousDeployment. See [Octopus Deploy/CI Build NuGet Packages](#continuousdeployment) above for more information
+ - `Continuous-Delivery-fallback-tag`: When using `mode: ContinuousDeployment` the value specified will be used as the pre-release tag for branches which do not have one specified.
  - `tag-prefix`: A regex which is used to trim git tags before processing (eg v1.0.0). Default is `[vV]` though this is just for illustrative purposes as we do a IgnoreCase match and could be `v`
 
 ## Branch configuration

Docs/configuration.md

@@ -1,5 +1,4 @@
 # Examples
-## Overview
 ![README](images/CommitGraph.png)
 
 At each commit sha GitVersion will calculate:
@@ -28,15 +27,7 @@ This is just a small sample of the way GitVersion works. The idea is you just pl
 If you have other branch types GitVersion is entirely configuration driven, so check out the [Configuration](#Configuration) section of the readme to understand how to make GitVersion work for you.
 
 ## GitFlow
-### Continuous Delivery mode
-TODO Example of GitFlow using continuous delivery mode
-
-### Continuous Deployment mode
-TODO Example of GitFlow using continuous deployment mode
+[See GitFlow Examples](branchingStrategies/gitFlowExamples.md)
 
 ## GitHubFlow
-### Continuous Delivery mode
-TODO Example of GitHubFlow using continuous delivery mode
-
-### Continuous Deployment mode
-TODO Example of GitHubFlow using continuous deployment mode
+[See GitHubFlow Examples](branchingStrategies/gitHubFlowExamples.md)

Docs/examples.md

@@ -4,7 +4,7 @@
 GitVersion calculates the semantic version, this will only change once per *release*. Read more at [version increments](./versionIncrements.md)
 
 ## How can GitVersion run for a shallow clone or checkout on server working directories
-GitVersion needs a proper git repository to run, some build servers do not do a proper clone which can cause issues. GitVersion has a feature called [dynamic repositories](dynamicRepositories.md) which solves this by cloning the repository and working against that clone instead of the working directory.
+GitVersion needs a proper git repository to run, some build servers do not do a proper clone which can cause issues. GitVersion has a feature called [dynamic repositories](Dynamic-Repositories.md) which solves this by cloning the repository and working against that clone instead of the working directory.
 
 ## I don't understand what SemVer is all about
 Not a problem, we have a quick introduction to SemVer which can be a good primer to read before reading [SemVer.org](http://semver.org)

Docs/faq.md

@@ -4,4 +4,4 @@ AppVeyor is the first build server which has a setup helper built into `GitVersi
  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
+ 4. Follow the prompts to generate an AppVeyor.yml file which works nicely with GitVersion

Docs/buildServerSetup/appVeyor.md renamed to docs/Build-Server-Setup/AppVeyor.md

@@ -13,7 +13,7 @@ GitVersion writes system parameters into TeamCity, so they will automatically be
 
 ## 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)
+  - If you want to use *checkout on server*, see [dynamic repositories](Dynamic-Repositories.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

Docs/buildServerSetup/dynamicRepositories.md renamed to docs/Build-Server-Setup/Dynamic-Repositories.md

@@ -0,0 +1,8 @@
+# Git setup
+
+## Remotes
+### upstream
+`upstream` should point at the main repository. Your workflow should be to fetch/pull from upstream. Update your local branches, then start working on a newly created feature branch
+
+### origin
+`origin` should point to your *fork*.

Docs/buildServerSetup/teamCity.md renamed to docs/Build-Server-Setup/teamCity.md

@@ -0,0 +1 @@
+theme: readthedocs