Merge pull request #4064 from HHobeck/feature/document-git-hub-flow-workflow

[Documentation]: Documenting the GitHubFlow workflow and create sequence diagrams

Author: arturcic

docs/input/docs/img/DocumentationSamplesForGitFlow_FeatureFromMainBranch.png

@@ -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)

docs/input/docs/img/DocumentationSamplesForGitHubFlow_FeatureBranch.png

@@ -4,22 +4,88 @@ 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
 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

docs/input/docs/img/DocumentationSamplesForGitHubFlow_ReleaseBranch.png

@@ -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: (?<version>[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?[/-](?<BranchName>.+)
+    prevent-increment:
+      when-current-commit-tagged: false
+    source-branches:
+    - main
+    pre-release-weight: 30000
+  hotfix:
+    increment: Patch
+    regex: ^hotfix(es)?[/-](?<BranchName>.+)
+    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: '[/-](?<number>\d+)'
+    regex: ^(pull|pull\-requests|pr)[/-]
+    source-branches:
+    - main
+    pre-release-weight: 30000
+  unknown:
+    increment: Patch
+    regex: (?<BranchName>.+)
+    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

docs/input/docs/img/DocumentationSamplesForGitHubFlow_VersionedReleaseBranch.png

@@ -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

docs/input/docs/learn/branching-strategies/gitflow/examples.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