diff --git a/docs/configuration.md b/docs/configuration.md index 99ee009a61..8c37a32afa 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,97 +1,242 @@ # Configuration -GitVersion 3.0 is mainly powered by configuration and no longer has branching strategies hard coded. +GitVersion 3.0 is mainly powered by configuration and no longer has branching +strategies hard coded. ## Configuration tool -If you run `GitVersion init` you will be launched into a configuration tool, it can help you configure GitVersion the way you want it. +If you run `GitVersion init` you will be launched into a configuration tool, it +can help you configure GitVersion the way you want it. -Once complete, the `init` command will create a `GitVersion.yml` file in the working directory. It can be the root repository directory or any subdirectory in case you have a single repository for more than one project or are restricted to commit into a subdirectory. +Once complete, the `init` command will create a `GitVersion.yml` file in the +working directory. It can be the root repository directory or any subdirectory +in case you have a single repository for more than one project or are restricted +to commit into a subdirectory. -**Note:** GitVersion ships with internal default configuration which works with GitHubFlow and GitFlow, probably with others too. +**Note:** GitVersion ships with internal default configuration which works with +GitHubFlow and GitFlow, probably with others too. -The *develop* branch is set to `ContinuousDeployment` mode by default as we have found that is generally what is needed when using GitFlow. +The *develop* branch is set to `ContinuousDeployment` mode by default as we have +found that is generally what is needed when using GitFlow. -You can run `GitVersion /showConfig` to see the effective configuration (defaults + overrides) +You can run `GitVersion /showConfig` to see the effective configuration +(defaults + overrides). -To create your config file just type `GitVersion init` in your repo directory after installing via chocolatey and we will create a sample (but commented out) config file. -Uncomment and modify as you need. +To create your config file just type `GitVersion init` in your repo directory +after installing via chocolatey and a minimal `GitVersion.yml` configuration +file will be created. Modify this as you need. ## Global configuration -The global configuration options are: +The global configuration look like this: - - **`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. Note: you can use `None` to skip updating the `AssemblyVersion` while still updating the `AssemblyFileVersion` and `AssemblyInformationVersion` attributes. - - - **`assembly-informational-format:`** Set this to any of the available [variables](/more-info/variables) to change the value of the `AssemblyInformationalVersion` attribute. Default set to `{InformationalVersion}`. It also supports string interpolation (`{MajorMinorPatch}+{Branch}`) - - - **`mode:`** Sets the mode of how GitVersion should create a new version. Read more at [versioning mode](./versioning-mode.md) - - - **`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. Default set to `ci`. - - - **`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`. - - - **`major-version-bump-message:`** The regex to match commit messages with to perform a major version increment. Default set to `'\+semver:\s?(breaking|major)'`, which will match occurrences of `+semver: major` and `+semver: breaking` in a commit message. - - - **`minor-version-bump-message:`** The regex to match commit messages with to perform a minor version increment. Default set to `'\+semver:\s?(feature|minor)'`, which will match occurrences of `+semver: feature` and `+semver: minor` in a commit message. - - - **`patch-version-bump-message:`** The regex to match commit messages with to perform a patch version increment. Default set to `'\+semver:\s?(fix|patch)'`, which will match occurrences of `+semver: fix` and `+semver: patch` in a commit message. - - - **`no-bump-message:`** Used to tell GitVersion not to increment when in Mainline development mode. Default `\+semver:\s?(none|skip)`, which will match occurrences of `+semver: none` and `+semver: skip` - - - **`legacy-semver-padding:`** The number of characters to pad `LegacySemVer` to in the `LegacySemVerPadded` [variable](/more-info/variables). Is default set to `4`, which will pad the `LegacySemVer` value of `3.0.0-beta1` to `3.0.0-beta0001`. - - - **`build-metadata-padding:`** The number of characters to pad `BuildMetaData` to in the `BuildMetaDataPadded` [variable](/more-info/variables). Is default set to `4`, which will pad the `BuildMetaData` value of `1` to `0001`. - - - **`commits-since-version-source-padding:`** The number of characters to pad `CommitsSinceVersionSource` to in the `CommitsSinceVersionSourcePadded` [variable](/more-info/variables). Is default set to `4`, which will pad the `CommitsSinceVersionSource` value of `1` to `0001`. - - - **`commit-message-incrementing:`** Sets whether it should be possible to increment the version with special syntax in the commit message. See the `*-version-bump-message` options above for details on the syntax. Default set to `Enabled`; set to `Disabled` to disable. - - - **`ignore:`** The header for ignore configuration - - **`sha:`** A sequence of SHAs to be excluded from the version calculations. Useful when there is a rogue commit in history yielding a bad version. - - **`commits-before:`** Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before: 2015-10-23T12:23:15`) to setup an exclusion range. Effectively any commit < `commits-before` will be ignored. - - - **`is-develop:`** Indicates this branch config represents develop in GitFlow +```yaml +next-version: 1.0 +assembly-versioning-scheme: MajorMinorPatch +assembly-informational-format: '{InformationalVersion}' +mode: ContinuousDelivery +continuous-delivery-fallback-tag: ci +tag-prefix: '[vV]' +major-version-bump-message: '\+semver:\s?(breaking|major)' +minor-version-bump-message: '\+semver:\s?(feature|minor)' +patch-version-bump-message: '\+semver:\s?(fix|patch)' +no-bump-message: '\+semver:\s?(none|skip)' +legacy-semver-padding: 4 +build-metadata-padding: 4 +commits-since-version-source-padding: 4 +commit-message-incrementing: Enabled +ignore: + sha: [] + commits-before: yyyy-MM-ddTHH:mm:ss +``` - **`is-release-branch:`** Indicates this branch config represents a release branch in GitFlow +And the description of the available 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, `assembly-versioning-scheme` tells GitVersion how +to treat the `AssemblyVersion` attribute. Useful to lock the major when using +Strong Naming. Note: you can use `None` to skip updating the `AssemblyVersion` +while still updating the `AssemblyFileVersion` and `AssemblyInformationVersion` +attributes. + +### assembly-informational-format +Set this to any of the available [variables](/more-info/variables) to change the +value of the `AssemblyInformationalVersion` attribute. Default set to +`{InformationalVersion}`. It also supports string interpolation +(`{MajorMinorPatch}+{Branch}`) + +### mode +Sets the `mode` of how GitVersion should create a new version. Read more at +[versioning mode](/reference/versioning-mode.md). + +### continuous-delivery-fallback-tag +When using `mode: ContinuousDeployment`, the value specified in +`continuous-delivery-fallback-tag` will be used as the pre-release tag for +branches which do not have one specified. Default set to `ci`. + +### 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`. + +### major-version-bump-message +The regex to match commit messages with to perform a major version increment. +Default set to `'\+semver:\s?(breaking|major)'`, which will match occurrences of +`+semver: major` and `+semver: breaking` in a commit message. + +### minor-version-bump-message +The regex to match commit messages with to perform a minor version increment. +Default set to `'\+semver:\s?(feature|minor)'`, which will match occurrences of +`+semver: feature` and `+semver: minor` in a commit message. + +### patch-version-bump-message +The regex to match commit messages with to perform a patch version increment. +Default set to `'\+semver:\s?(fix|patch)'`, which will match occurrences of +`+semver: fix` and `+semver: patch` in a commit message. + +### no-bump-message +Used to tell GitVersion not to increment when in Mainline development mode. +Default `\+semver:\s?(none|skip)`, which will match occurrences of `+semver: +none` and `+semver: skip` + +### legacy-semver-padding +The number of characters to pad `LegacySemVer` to in the `LegacySemVerPadded` +[variable](/more-info/variables). Is default set to `4`, which will pad the +`LegacySemVer` value of `3.0.0-beta1` to `3.0.0-beta0001`. + +### build-metadata-padding +The number of characters to pad `BuildMetaData` to in the `BuildMetaDataPadded` +[variable](/more-info/variables). Is default set to `4`, which will pad the +`BuildMetaData` value of `1` to `0001`. + +### commits-since-version-source-padding +The number of characters to pad `CommitsSinceVersionSource` to in the +`CommitsSinceVersionSourcePadded` [variable](/more-info/variables). Is default +set to `4`, which will pad the `CommitsSinceVersionSource` value of `1` to +`0001`. + +### commit-message-incrementing +Sets whether it should be possible to increment the version with special syntax +in the commit message. See the `*-version-bump-message` options above for +details on the syntax. Default set to `Enabled`; set to `Disabled` to disable. + +### ignore +The header for ignore configuration. + +#### sha +A sequence of SHAs to be excluded from the version calculations. Useful when +there is a rogue commit in history yielding a bad version. + +#### commits-before +Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before: +2015-10-23T12:23:15`) to setup an exclusion range. Effectively any commit before +`commits-before` will be ignored. ## Branch configuration - Then we have branch specific configuration, which looks something like this: ```yaml branches: master: - tag: + mode: ContinuousDelivery + tag: '' + increment: Patch + prevent-increment-of-merged-branch-version: true + track-merge-target: false + is-develop: false + is-release-branch: false + releases?[/-]: + mode: ContinuousDelivery + tag: beta increment: Patch prevent-increment-of-merged-branch-version: true + track-merge-target: false + is-develop: false + is-release-branch: true + features?[/-]: + mode: ContinuousDelivery + tag: useBranchName + increment: Inherit + prevent-increment-of-merged-branch-version: false + track-merge-target: false + is-develop: false + is-release-branch: false (pull|pull\-requests|pr)[/-]: + mode: ContinuousDelivery tag: PullRequest increment: Inherit - track-merge-target: true + prevent-increment-of-merged-branch-version: false tag-number-pattern: '[/-](?\d+)[-/]' + track-merge-target: false + is-develop: false + is-release-branch: false + hotfix(es)?[/-]: + mode: ContinuousDelivery + tag: beta + increment: Patch + prevent-increment-of-merged-branch-version: false + track-merge-target: false + is-develop: false + is-release-branch: false + support[/-]: + mode: ContinuousDelivery + tag: '' + increment: Patch + prevent-increment-of-merged-branch-version: true + track-merge-target: false + is-develop: false + is-release-branch: false + dev(elop)?(ment)?$: + mode: ContinuousDeployment + tag: unstable + increment: Minor + prevent-increment-of-merged-branch-version: false + track-merge-target: true + is-develop: true + is-release-branch: false ``` -The options in here are: +We don't envision many people needing to change most of these configuration +values, but here they are if you need to: + +### branches +The header for all the individual branch configuration. + +### mode +Same as for the [global configuration, explained above](#mode). - - **`branches:`** The header for all the individual branch configuration. +### tag +The pre release tag to use for this branch. Use the value `useBranchName` to use +the branch name instead. For example `feature/foo` would become a pre-release +tag of `foo` with this value. Use the value `{BranchName}` as a placeholder to +insert the branch name. For example `feature/foo` would become a pre-release tag +of `alpha.foo` with the value of `alpha.{BranchName}`. - - **`mode:`** Same as above +**Note:** To clear a default use an empty string: `tag: ''` - - **`tag:`** The pre release tag to use for this branch. - Use the value `useBranchName` to use the branch name instead. For example `feature/foo` would become a pre-release tag of `foo` with this value. - Use the value `{BranchName}` as a placeholder to insert the branch name. For example `feature/foo` would become a pre-release tag of `alpha.foo` with the value of `alpha.{BranchName}`. - **Note:** To clear a default use an empty string: `tag: ""` +### increment +The part of the SemVer to increment when GitVersion detects it needs to be (i.e +commit after a tag) - - **`increment:`** the part of the SemVer to increment when GitVersion detects it needs to be (i.e commit after a tag) +### prevent-increment-of-merged-branch-version +When `release-2.0.0` is merged into master, we want master to build `2.0.0`. If +`release-2.0.0` is merged into develop we want it to build `2.1.0`, this option +prevents incrementing after a versioned branch is merged - - **`prevent-increment-of-merged-branch-version:`** When `release-2.0.0` is merged into master, we want master to build `2.0.0`. - If `release-2.0.0` is merged into develop we want it to build `2.1.0`, this option prevents incrementing after a versioned branch is merged +### tag-number-pattern +Pull requests require us to extract the pre-release number out of the branch +name so `refs/pulls/534/merge` builds as `PullRequest.534`. This is a regex with +a named capture group called `number`. + +If the branch `mode` is set to `ContinuousDeployment`, then the extracted +`number` is appended to the name of the pre-release tag and the number portion +is the number of commits since the last tag. This enables consecutive commits to +the pull request branch to generate unique full semantic version numbers when +the branch is configured to use ContinuousDeployment mode. + +**Example usage:** - - **`tag-number-pattern:`** Pull requests require us to extract the pre-release number out of the branch name so `refs/pulls/534/merge` builds as `PullRequest.534`. - This is a regex with a named capture group called `number` - If the branch mode is set to ContinuousDeployment, then the extracted `number` is appended to the name of the pre-release tag and the number portion is the number of commits since the last tag. - This enables consecutive commits to the pull request branch to generate unique full semantic version numbers when the branch is configured to use ContinuousDeployment mode. - Example usage: ```yaml branches: (pull|pull\-requests|pr)[/-]: @@ -102,6 +247,13 @@ branches: tag-name-pattern: '[/-](?\d+)[-/]' ``` - - **`track-merge-target:`** Strategy which will look for tagged merge commits directly off the current branch. For example `develop` → `release/1.0.0` → merge into `master` and tag `1.0.0`. The tag is *not* on develop, but develop should be version `1.0.0` now. +### track-merge-target +Strategy which will look for tagged merge commits directly off the current +branch. For example `develop` → `release/1.0.0` → merge into `master` and tag +`1.0.0`. The tag is *not* on develop, but develop should be version `1.0.0` now. + +### is-develop +Indicates this branch config represents develop in GitFlow. -We don't envision many people needing to change most of these configuration values, but they are there if you need to. +### is-release-branch +Indicates this branch config represents a release branch in GitFlow. \ No newline at end of file diff --git a/docs/reference/continuous-delivery.md b/docs/reference/continuous-delivery.md index 60b28c5012..a71078eb06 100644 --- a/docs/reference/continuous-delivery.md +++ b/docs/reference/continuous-delivery.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 Wikipedia](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) \ No newline at end of file diff --git a/docs/reference/continuous-deployment.md b/docs/reference/continuous-deployment.md index c1915d2c51..ff8bd8800f 100644 --- a/docs/reference/continuous-deployment.md +++ b/docs/reference/continuous-deployment.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 \ No newline at end of file diff --git a/docs/reference/mainline-development.md b/docs/reference/mainline-development.md index 3a5fa534d9..bcdeda07cd 100644 --- a/docs/reference/mainline-development.md +++ b/docs/reference/mainline-development.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 +``` \ No newline at end of file diff --git a/docs/reference/versioning-mode.md b/docs/reference/versioning-mode.md new file mode 100644 index 0000000000..820756121f --- /dev/null +++ b/docs/reference/versioning-mode.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`. \ No newline at end of file diff --git a/docs/versioning-mode.md b/docs/versioning-mode.md deleted file mode 100644 index 41eae53e4f..0000000000 --- a/docs/versioning-mode.md +++ /dev/null @@ -1,42 +0,0 @@ -# Versioning modes -GitVersion has multiple modes to fit different different ways of working. - - -## Continuous Delivery -This is the default mode, GitVersion calculates the next version and will use that until that is released. 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. - -## Continuous deployment -Sometimes you just want the version to keep changing and continuously deploy. A good case for this is when using Octopus deploy, as you cannot publish the same version of a package into the same feed. - -For this mode we followed the logic in this blog post by Xavier Decoster on the issues of incrementing automatically - http://www.xavierdecoster.com/semantic-versioning-auto-incremented-nuget-package-versions - -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. Mainline development. - -## Mainline development -Mainline development works more like the Continuous Delivery mode, except that it tells GitVersion to *infer* releases from merges and commits to `master`. - -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) -1. Walk all commits from the base version commit -1. When a merge commit is found: - - Calculate increments for each direct commit on master - - Calculate the increment for the branch -1. Calculate increments for each remaining direct commit -1. 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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index a0adafb992..29a124fb52 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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 diff --git a/src/GitVersionCore.Tests/DocumentationTests.cs b/src/GitVersionCore.Tests/DocumentationTests.cs index 5e6b89e39e..565e86f671 100644 --- a/src/GitVersionCore.Tests/DocumentationTests.cs +++ b/src/GitVersionCore.Tests/DocumentationTests.cs @@ -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; } } \ No newline at end of file