diff --git a/docs/input/docs/img/DocumentationSamplesForGitFlow_FeatureFromMainBranch.png b/docs/input/docs/img/DocumentationSamplesForGitFlow_FeatureFromMainBranch.png index ab22724ec9..af6daf6711 100644 Binary files a/docs/input/docs/img/DocumentationSamplesForGitFlow_FeatureFromMainBranch.png and b/docs/input/docs/img/DocumentationSamplesForGitFlow_FeatureFromMainBranch.png differ diff --git a/docs/input/docs/img/DocumentationSamplesForGitHubFlow_FeatureBranch.png b/docs/input/docs/img/DocumentationSamplesForGitHubFlow_FeatureBranch.png new file mode 100644 index 0000000000..af6daf6711 Binary files /dev/null and b/docs/input/docs/img/DocumentationSamplesForGitHubFlow_FeatureBranch.png differ diff --git a/docs/input/docs/img/DocumentationSamplesForGitHubFlow_ReleaseBranch.png b/docs/input/docs/img/DocumentationSamplesForGitHubFlow_ReleaseBranch.png new file mode 100644 index 0000000000..22d7a76e47 Binary files /dev/null and b/docs/input/docs/img/DocumentationSamplesForGitHubFlow_ReleaseBranch.png differ diff --git a/docs/input/docs/img/DocumentationSamplesForGitHubFlow_VersionedReleaseBranch.png b/docs/input/docs/img/DocumentationSamplesForGitHubFlow_VersionedReleaseBranch.png new file mode 100644 index 0000000000..f95e478d5c Binary files /dev/null and b/docs/input/docs/img/DocumentationSamplesForGitHubFlow_VersionedReleaseBranch.png differ diff --git a/docs/input/docs/learn/branching-strategies/gitflow/examples.md b/docs/input/docs/learn/branching-strategies/gitflow/examples.md index 971be376ae..1511b617fb 100644 --- a/docs/input/docs/learn/branching-strategies/gitflow/examples.md +++ b/docs/input/docs/learn/branching-strategies/gitflow/examples.md @@ -86,6 +86,15 @@ iterations. Release branches are taken from `main` (or from `develop`) and will be merged back afterwards. Finally the `main` branch is tagged with the released version. +Release branches can be used in the `GitFlow` as well as `GitHubFlow` workflow. +Sometimes you want to start on a large feature which may take a while +to stabilize so you want to keep it off main. +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. + ### Create release branch ![GitFlow](/docs/img/DocumentationSamplesForGitFlow\_ReleaseBranch.png) diff --git a/docs/input/docs/learn/branching-strategies/githubflow/examples.md b/docs/input/docs/learn/branching-strategies/githubflow/examples.md index 4a71e6dc4f..0f79be951a 100644 --- a/docs/input/docs/learn/branching-strategies/githubflow/examples.md +++ b/docs/input/docs/learn/branching-strategies/githubflow/examples.md @@ -4,17 +4,65 @@ Title: GitHubFlow Examples RedirectFrom: docs/git-branching-strategies/githubflow-examples --- -## Feature branch +These examples are illustrating the usage of the supported `GitHubFlow` workflow +in GitVersion. To enable this workflow, the builtin template +[GitHubFlow/v1](/docs/workflows/GitHubFlow/v1.json) needs to be referenced in the +configuration as follows: +```yaml +workflow: GitHubFlow/v1 +mode: ContinuousDelivery +``` -![GitHubFlow](/docs/img/githubflow_feature-branch.png) +Where +the [continuous deployment][continuous-deployment] mode for no branches, +the [continuous delivery][continuous-delivery] mode for +`main` branch and +the [manual deployment][manual-deployment] mode +for `release`, `feature` and `unknown` branches are specified. -## Pull requests +This configuration allows you to publish CI (Continuous Integration) builds +from `main` branch to an artifact repository. +All other branches are manually published. Read more about this at +[version increments](/docs/reference/version-increments). -![GitHubFlow](/docs/img/githubflow_pull-request.png) +:::{.alert .alert-info} +The _continuous delivery_ mode has been used for the `main` branch in this +examples (specified as a fallback on the root +configuration layer) to illustrate how the version increments are applied. +In production context the _continuous deployment_ mode might be a better +option when e.g. the release process is automated or the commits are tagged +by the pipeline automatically. +::: -## Release branch +## Feature Branch -Release branches can be used in GitHubFlow as well as GitFlow. Sometimes you +Feature branches can be used in the `GitHubFlow` workflow to implement a +feature or fix a bug in an isolated environment. Feature branches will take +the feature +branch name and use that as the pre-release label. Feature branches will be +created from a `main` or `release` branch. + +### Create feature branch from main + +![GitHubFlow](/docs/img/DocumentationSamplesForGitHubFlow_FeatureBranch.png) + +:::{.alert .alert-info} +After the feature branch is merged, the version on `main` is `2.0.0-5`. +This is due to `main` running in _continuous delivery_ mode. If `main` was +configured to use _continuous deployment_ the version would be `2.0.0`. +::: + +## Release Branches + +Release branches are used for major, minor and patch releases to stabilize a RC +(Release Candidate) or to integrate features/hotfixes (in parallel) targeting +different +iterations. Release branches are taken from `main` and will +be merged back afterwards. Finally the `main` branch is tagged with the +released version. + +Release branches can be used in the `GitHubFlow` as well as `GitFlow` workflow. +Sometimes you want to start on a large feature which may take a while to stabilize so you want to keep it off main. 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 @@ -22,4 +70,22 @@ 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](/docs/img/githubflow_release-branch.png) +### Create release branch + +![GitFlow](/docs/img/DocumentationSamplesForGitHubFlow_ReleaseBranch.png) + +### Create release branch with version + +![GitFlow](/docs/img/DocumentationSamplesForGitHubFlow_VersionedReleaseBranch.png) + +## To Contribute + +See [contributing examples](/docs/learn/branching-strategies/contribute-examples). + +### Source + +See `DocumentationSamplesForGitHubFlow.cs`. To update, modify then run test. + +[continuous-deployment]: /docs/reference/modes/continuous-deployment +[continuous-delivery]: /docs/reference/modes/continuous-delivery +[manual-deployment]: /docs/reference/modes/manual-deployment diff --git a/docs/input/docs/reference/configuration.md b/docs/input/docs/reference/configuration.md index 57df2661aa..e185710262 100644 --- a/docs/input/docs/reference/configuration.md +++ b/docs/input/docs/reference/configuration.md @@ -37,6 +37,7 @@ The following supported workflow configurations are available in GitVersion and - GitFlow (GitFlow/v1) - GitHubFlow (GitHubFlow/v1) +- TrunkBased (TrunkBased/preview1) Example of using a `GitHubFlow` workflow with a different `tag-prefix`: @@ -338,6 +339,91 @@ is-release-branch: false is-main-branch: false ``` +The preview built-in configuration (experimental usage only) for the `TrunkBased` workflow (`workflow: TrunkBased/preview1`) looks like: + +```yaml +assembly-versioning-scheme: MajorMinorPatch +assembly-file-versioning-scheme: MajorMinorPatch +tag-prefix: '[vV]?' +version-in-branch-pattern: (?[vV]?\d+(\.\d+)?(\.\d+)?).* +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)' +tag-pre-release-weight: 60000 +commit-date-format: yyyy-MM-dd +merge-message-formats: {} +update-build-number: true +semantic-version-format: Strict +strategies: +- Mainline +- ConfiguredNextVersion +branches: + main: + mode: ContinuousDeployment + label: '' + increment: Patch + prevent-increment: + of-merged-branch: true + when-current-commit-tagged: true + track-merge-target: false + regex: ^master$|^main$ + source-branches: [] + tracks-release-branches: false + is-release-branch: false + is-main-branch: true + pre-release-weight: 55000 + feature: + increment: Minor + regex: ^features?[/-](?.+) + prevent-increment: + when-current-commit-tagged: false + source-branches: + - main + pre-release-weight: 30000 + hotfix: + increment: Patch + regex: ^hotfix(es)?[/-](?.+) + prevent-increment: + when-current-commit-tagged: false + source-branches: + - main + pre-release-weight: 30000 + pull-request: + mode: ContinuousDelivery + label: PullRequest + increment: Inherit + label-number-pattern: '[/-](?\d+)' + regex: ^(pull|pull\-requests|pr)[/-] + source-branches: + - main + pre-release-weight: 30000 + unknown: + increment: Patch + regex: (?.+) + prevent-increment: + when-current-commit-tagged: false + source-branches: + - main + pre-release-weight: 30000 +ignore: + sha: [] +mode: ContinuousDelivery +label: '{BranchName}' +increment: Inherit +prevent-increment: + of-merged-branch: false + when-branch-merged: false + when-current-commit-tagged: true +track-merge-target: false +track-merge-message: true +commit-message-incrementing: Enabled +regex: '' +tracks-release-branches: false +is-release-branch: false +is-main-branch: false +``` + The details of the available options are as follows: ### workflow diff --git a/docs/input/docs/reference/modes/continuous-delivery.md b/docs/input/docs/reference/modes/continuous-delivery.md index a1e824ca91..d1d2a1e712 100644 --- a/docs/input/docs/reference/modes/continuous-delivery.md +++ b/docs/input/docs/reference/modes/continuous-delivery.md @@ -2,75 +2,39 @@ Order: 20 Title: Continuous Delivery Description: | - Continuous Delivery is the default versioning mode. In this mode, - GitVersion calculates the next version and will use that until that is - released. + Sometimes you just want the version to keep changing and deploy continuously + to an testing system. In this case, Continuous Delivery is a good mode to + operate GitVersion by. RedirectFrom: docs/reference/versioning-modes/continuous-delivery --- -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. +Continuous Delivery is the process of checking into a branch, running all the +tests and if everything goes green it is automatically pushed to a testing system. -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. +A good case for Continuous Delivery is when using Octopus deploy, as you +cannot publish the same version of a package into the same feed. -In essence continuous delivery means: - -* Your code is automatically built and tested -* 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 main 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] 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]. -To change the mode to Continuous Delivery, change your -[configuration][configuration] to: - -```yaml -mode: ContinuousDelivery -``` +For this mode we follow the logic in [this blog post by Xavier Decoster][blog] +on the issues of incrementing automatically. ## 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: +Continuous delivery is good when you deploy continuously to an testing system. -* 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 +* 1.1.0-3 +* 1.1.0-2 (tag: 1.1.0-2) <-- This is the version which has been deployed on testing +* 1.1.0-1 +* 1.1.1-0 -Tags are required in this mode to communicate when the release is done as it's -an external manual process. +Tags are not required but optional in this mode to communicate when the release +is done as it's an automated process. ## Resources -* [Continuous Delivery on Wikipedia][wikipedia] -* [Continuous Delivery, the book][book] +* [Configuration][configuration] +* [Semantic Versioning & auto-incremented NuGet package versions][blog] +* [Continuous delivery][wikipedia] -[book]: https://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912 [configuration]: /docs/reference/configuration -[continuous-deployment]: /docs/reference/modes/continuous-deployment -[mainline]: /docs/reference/modes/mainline +[blog]: https://www.xavierdecoster.com/semantic-versioning-auto-incremented-nuget-package-versions [wikipedia]: https://en.wikipedia.org/wiki/Continuous_delivery diff --git a/docs/input/docs/reference/modes/continuous-deployment.md b/docs/input/docs/reference/modes/continuous-deployment.md index 999256d779..852936e67f 100644 --- a/docs/input/docs/reference/modes/continuous-deployment.md +++ b/docs/input/docs/reference/modes/continuous-deployment.md @@ -3,42 +3,32 @@ Order: 30 Title: Continuous Deployment Description: | Sometimes you just want the version to keep changing and deploy continuously. - In this case, Continuous Deployment is a good mode to operate GitVersion by. RedirectFrom: docs/reference/versioning-modes/continuous-deployment --- -Continuous Deployment is the process of checking into main, running all the -tests and if everything goes green it is automatically pushed to production. - -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. +Continuous Deployment is the process of checking into main and automatically +deploying to production. 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]. +## How Continuous Deployment affects GitVersion -### Usage +The thing about continuous deployment is that there will be only one version +to deploy on production. This means that GitVersion will build +**the same semantic version** for every commit until it has been tagged. For instance: -By default GitVersion is set up to do Continuous Deployment versioning on the -`develop` branch, but for all other branches, [Continuous -Delivery][continuous-delivery] is the default mode. From version 3 of GitVersion -this behavior is [configurable][configuration]. +* 1.2.0 +* 1.1.0 (tag: 1.1.0) <-- This is the version which has been deployed on production +* 1.1.0 +* 1.1.1 -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] from `ContinuousDelivery` -to `ContinuousDeployment` and the version will then increment each commit, -giving you the features of GitVersion with continuous deployment: +Tags are required in this mode to communicate when the deployement happens on production. -```yaml -mode: ContinuousDeployment -``` +## Resources + +* [Configuration][configuration] +* [Semantic Versioning & auto-incremented NuGet package versions][blog] -[blog]: https://www.xavierdecoster.com/semantic-versioning-auto-incremented-nuget-package-versions [configuration]: /docs/reference/configuration -[continuous-delivery]: /docs/reference/modes/continuous-delivery -[mainline]: /docs/reference/modes/mainline +[blog]: https://www.xavierdecoster.com/semantic-versioning-auto-incremented-nuget-package-versions diff --git a/docs/input/docs/reference/modes/mainline.md b/docs/input/docs/reference/modes/mainline.md deleted file mode 100644 index d88129e418..0000000000 --- a/docs/input/docs/reference/modes/mainline.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -Order: 40 -Title: Mainline Development -Description: | - Mainline Development versioning mode works like the Continuous Delivery, - except that it tells GitVersion to *infer* releases from merges and commits - to `main`. -RedirectFrom: docs/reference/versioning-modes/mainline-development ---- - -:::{.alert .alert-danger} - **`Mainline` mode was deprecated in version 6 of GitVersion.** See [the following pull request](https://github.com/GitTools/GitVersion/pull/3844) for details. -::: - -Mainline Development is enabled when using [GitHubFlow][githubflow] or any other -strategy where you develop on `main`. The main rule of mainline development is -that **main 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. - -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 main. The behaviour of this mode is as follows: - -1. Calculate 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 main - * 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][mainline-img] - -:::{.alert .alert-warning} -**Warning** - -This approach can slow down over time, we recommend to tag -intermittently (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] -versioning on all branches but `develop` (which does [Continuous -Deployment][continuous-deployment] by default). To change the [versioning -mode][modes] to Mainline Development, just change the [configuration][configuration] as such: - -```yaml -mode: Mainline -``` - -[configuration]: /docs/reference/configuration -[continuous-delivery]: /docs/reference/modes/continuous-delivery -[continuous-deployment]: /docs/reference/modes/continuous-deployment -[githubflow]: /docs/learn/branching-strategies/githubflow -[mainline-img]: /docs/img/mainline-mode.png -[modes]: /docs/reference/modes diff --git a/docs/input/docs/reference/modes/manual-deployment.md b/docs/input/docs/reference/modes/manual-deployment.md new file mode 100644 index 0000000000..2b9a7eeafb --- /dev/null +++ b/docs/input/docs/reference/modes/manual-deployment.md @@ -0,0 +1,37 @@ +--- +Order: 10 +Title: Manual Deployment +Description: | + The Manual Deployment mode can be used to remain on the same pre-released + version until it has been deployed dedicatedly. +RedirectFrom: docs/reference/versioning-modes/manual-deployment +--- + +Having not the necessity to deploy the build artifacts on every commit is an +indecation of using the __Manual Deployment__ mode. This mode can be used to +remain on the same pre-released version until it has been deployed dedicatedly. + +## How Manual Deployment affects GitVersion + +The thing about manual deployment is that there will be _multiple_ candidates +to deploy on testing 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-2+1 +* 1.1.0-1+2 (tag: 1.1.0-1) <-- This is the version which has been deployed on testing +* 1.1.0-1+1 +* 1.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 + +* [Configuration][configuration] +* [Continuous Delivery on Wikipedia][wikipedia] +* [Continuous Delivery, the book][book] + +[configuration]: /docs/reference/configuration +[book]: https://www.amazon.com/Continuous-Delivery-Deployment-Automation-Addison-Wesley/dp/0321601912 +[wikipedia]: https://en.wikipedia.org/wiki/Continuous_delivery diff --git a/docs/input/docs/workflows/TrunkBased/v1.yml b/docs/input/docs/workflows/TrunkBased/preview1.yml similarity index 100% rename from docs/input/docs/workflows/TrunkBased/v1.yml rename to docs/input/docs/workflows/TrunkBased/preview1.yml diff --git a/src/GitVersion.Configuration/GitVersion.Configuration.csproj b/src/GitVersion.Configuration/GitVersion.Configuration.csproj index 17d9bbd4c4..cf3b09fcfe 100644 --- a/src/GitVersion.Configuration/GitVersion.Configuration.csproj +++ b/src/GitVersion.Configuration/GitVersion.Configuration.csproj @@ -40,10 +40,10 @@ - + - + diff --git a/src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitHubFlow.cs b/src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitHubFlow.cs index 0f0aaf4202..cba4301309 100644 --- a/src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitHubFlow.cs +++ b/src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitHubFlow.cs @@ -75,6 +75,8 @@ public void FeatureBranch(bool withPullRequestIntoMain) fixture.SequenceDiagram.Activate("main"); fixture.MakeACommit(); fixture.AssertFullSemver("2.0.0-6", configuration); + fixture.ApplyTag("2.0.0"); + fixture.AssertFullSemver("2.0.0", configuration); } [TestCase(false)] @@ -216,6 +218,8 @@ public void ReleaseBranch(bool withPullRequestIntoMain) fixture.SequenceDiagram.Activate("main"); fixture.MakeACommit(); fixture.AssertFullSemver("1.3.1-6", configuration); + fixture.ApplyTag("1.3.1"); + fixture.AssertFullSemver("1.3.1", configuration); } [TestCase(false)] @@ -357,6 +361,8 @@ public void VersionedReleaseBranch(bool withPullRequestIntoMain) fixture.SequenceDiagram.Activate("main"); fixture.MakeACommit(); fixture.AssertFullSemver("2.3.1-6", configuration); + fixture.ApplyTag("2.3.1"); + fixture.AssertFullSemver("2.3.1", configuration); } [TestCase(false)]