Skip to content

Commit

Permalink
(GH-1932) Linting and ordering of branching strategy
Browse files Browse the repository at this point in the history
  • Loading branch information
@gep13 @arturcic
gep13 authored and arturcic committed Dec 19, 2019
1 parent 0db1cee commit 1772a1d
Show file tree
Hide file tree
Showing 8 changed files with 216 additions and 93 deletions.
14 changes: 10 additions & 4 deletions docs/input/docs/git-branching-strategies/converting-to-gitflow.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
# Converting to GitFlow
Converting to GitFlow is simple. Whenever you need to convert, simply do the following
---
Order: 60
Title: Converting to GitFlow
---

```
Converting to GitFlow is simple. Whenever you need to convert, simply do the
following

```shell
git checkout master
git checkout -b develop
git push upstream develop
```

Afterwards you need to set `develop` to be your default branch. And now all development happens on the `develop` branch
Afterwards you need to set `develop` to be your default branch. And now all
development happens on the `develop` branch
22 changes: 15 additions & 7 deletions docs/input/docs/git-branching-strategies/creating-updating-examples.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,19 @@
# Creating/Updating Examples
The examples are generated by GitVersion tests, there are a number of services which will then turn the sequence diagram text into an image to use in the docs. Here are some links which could be useful
---
Order: 70
Title: Creating/Updating Examples
---

- [PlantUML Sequence Diagrams](http://www.plantuml.com/sequence.html)
- [CodeUML Online editor](http://www.codeuml.com/)
- [PlantText Online editor](http://www.planttext.com/planttext)
- [PlantUML gist renderer](http://uml.mvnsearch.org)
The examples are generated by GitVersion tests, there are a number of services
which will then turn the sequence diagram text into an image to use in the docs.
Here are some links which could be useful

The tests are quite simple. Using the methods on the `fixture` itself will record that action in the sequence diagram. If you do not want the action recorded perform the action directly on the repository (`fixture.Repository.`)
- [PlantUML Sequence Diagrams](http://www.plantuml.com/sequence.html)
- [CodeUML Online editor](http://www.codeuml.com/)
- [PlantText Online editor](http://www.planttext.com/planttext)
- [PlantUML gist renderer](http://uml.mvnsearch.org)

The tests are quite simple. Using the methods on the `fixture` itself will
record that action in the sequence diagram. If you do not want the action
recorded perform the action directly on the repository (`fixture.Repository.`)

The tests for the examples should all live at [DocumentationSamples.cs](https://github.com/GitTools/GitVersion/blob/master/src/GitVersionCore.Tests/IntegrationTests/DocumentationSamples.cs)
66 changes: 49 additions & 17 deletions docs/input/docs/git-branching-strategies/gitflow-examples.md
View file
Original file line number Diff line number Diff line change
@@ -1,53 +1,85 @@
# GitFlow Examples
These examples are using the *default* configuration with GitVersion. Which is [continuous deployment](../reference/continuous-deployment.md) mode for `develop` and [continuous delivery](../reference/continuous-delivery.md) mode for all other branches.
---
Order: 40
Title: GitFlow Examples
---

This default configuration allows you to publish CI builds from develop to a CI MyGet feed, or another CI feed. Then all other branches are manually released then tagged. Read more about this at [version increments](../more-info/version-increments.md).
These examples are using the *default* configuration with GitVersion. Which is
[continuous deployment](../reference/continuous-deployment.md) mode for
`develop` and [continuous delivery](../reference/continuous-delivery.md) mode
for all other branches.

This default configuration allows you to publish CI builds from develop to a CI
MyGet feed, or another CI feed. Then all other branches are manually released
then tagged. Read more about this at [version increments](../more-info/version-increments.md).

## Feature Branches
Feature branches will take the feature branch name and use that as the pre-release tag.

Feature branches will take the feature branch name and use that as the
pre-release tag.

![GitFlow](img/05119d0cd4ecaaefff94_feature-branch.png)

Notice after the feature branch is merged, the version on `develop` is `1.3.0-alpha.3`. This is due to `develop` running in *continuous deployment* mode. If you configured `develop` to use *continuous delivery* the version would still be `1.3.0-alpha.1` and you would have to use release tags to increment the `alpha.1`.
Notice after the feature branch is merged, the version on `develop` is
`1.3.0-alpha.3`. This is due to `develop` running in *continuous deployment*
mode. If you configured `develop` to use *continuous delivery* the version would
still be `1.3.0-alpha.1` and you would have to use release tags to increment the
`alpha.1`.

You can see the difference on the feature branch itself, notice the version is the same before and after the commit on the feature branch? Only the metadata has changed. If you released the feature branch artifacts then tagged the commit, the following commit would increase to `-beta.2`.
You can see the difference on the feature branch itself, notice the version is
the same before and after the commit on the feature branch? Only the metadata
has changed. If you released the feature branch artifacts then tagged the
commit, the following commit would increase to `-beta.2`.

## Pull Request

Because feature branches are most likely pushed to a fork, we are showing the
pull request branch name which is created when you submit a pull request

![GitFlow](img/09fdf46995b771f3164a_pull-request.png)


## Hotfix Branches
Hotfix branches are used when you need to do a *patch* release in GitFlow and are always created off `master`

![GitFlow](img/f26ae57adbd9b74f74c4_hotfix.png)
Hotfix branches are used when you need to do a *patch* release in GitFlow and
are always created off `master`

![GitFlow](img/f26ae57adbd9b74f74c4_hotfix.png)

## Minor Release Branches
Release branches are used for both major and minor releases for stabilisation before a release. Release branches are taken off `develop` then merged to both `develop` and `master`. Finally `master` is tagged with the released version.

![GitFlow](img/6d33d35a70a777608fa1_minor-release.png)
Release branches are used for both major and minor releases for stabilisation
before a release. Release branches are taken off `develop` then merged to both
`develop` and `master`. Finally `master` is tagged with the released version.

![GitFlow](img/6d33d35a70a777608fa1_minor-release.png)

## Major Release Branches
Major releases are just like minor releases, the difference is you bump the major in the release branch name.

![GitFlow](img/39f9d8b8b007c82f1f80_major-release.png)
Major releases are just like minor releases, the difference is you bump the
major in the release branch name.

![GitFlow](img/39f9d8b8b007c82f1f80_major-release.png)

## Support Branches
Support branches are not really covered in GitFlow, but are essential if you need to maintain multiple major versions at the same time. You could use support branches for supporting minor releases as well. If you are just supporting the majors, then name your branch `support/<major>.x` (i.e `support/1.x`), to support minors use `support/<major>.<minor>.x` or `support/<major>.<minor>.0`. (i.e `support/1.3.x` or `support/1.3.0`)

Support branches are not really covered in GitFlow, but are essential if you
need to maintain multiple major versions at the same time. You could use support
branches for supporting minor releases as well. If you are just supporting the
majors, then name your branch `support/<major>.x` (i.e `support/1.x`), to
support minors use `support/<major>.<minor>.x` or `support/<major>.<minor>.0`.
(i.e `support/1.3.x` or `support/1.3.0`)

### Hotfix
Depending on what you name your support branch, you may or may not need a hotfix branch. Naming it `support/1.x` will automatically bump the patch, if you name it `support/1.3.0` then the version in branch name rule will kick in and the patch *will not* automatically bump, meaning you have to use hotfix branches.
![GitFlow](img/b035b8ca99bd34239518_support-hotfix.png)

Depending on what you name your support branch, you may or may not need a hotfix
branch. Naming it `support/1.x` will automatically bump the patch, if you name
it `support/1.3.0` then the version in branch name rule will kick in and the
patch *will not* automatically bump, meaning you have to use hotfix branches.
![GitFlow](img/b035b8ca99bd34239518_support-hotfix.png)

### Minor Release
![GitFlow](img/2167fb1c4a5cf84edfd8_support-minor.png)

![GitFlow](img/2167fb1c4a5cf84edfd8_support-minor.png)

## To Update/Contribute

See [creating/updating examples](creating-updating-examples.md)
8 changes: 6 additions & 2 deletions docs/input/docs/git-branching-strategies/gitflow-examples_complete.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# GitFlow Examples
---
Order: 80
Title: GitFlow Examples
---

![GitFlow](http://uml.mvnsearch.org/gist/cf053d7f5d336ae9f7bb)

## Source

See `DocumentationSamples.GitFlowExample`. To update, modify then run test. Update [https://gist.github.com/JakeGinnivan/cf053d7f5d336ae9f7bb](https://gist.github.com/JakeGinnivan/cf053d7f5d336ae9f7bb)
See `DocumentationSamples.GitFlowExample`. To update, modify then run test.
Update [https://gist.github.com/JakeGinnivan/cf053d7f5d336ae9f7bb](https://gist.github.com/JakeGinnivan/cf053d7f5d336ae9f7bb)
92 changes: 61 additions & 31 deletions docs/input/docs/git-branching-strategies/gitflow.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,48 @@
#GitFlow
GitFlow allows more structured releases, and GitVersion will derive sensible SemVer compatible versions from this structure.
---
Order: 20
Title: GitFlow
---

GitFlow allows more structured releases, and GitVersion will derive sensible
SemVer compatible versions from this structure.

## Resources

## Assumptions:

* Using [GitFlow branching model](http://nvie.com/git-model/) which always has a master and a develop branch
* 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)
* 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
* 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:
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.
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`
`mergeVersion` => the SemVer extracted from `targetCommit.Message`

* major: `mergeVersion.Major`
* minor: `mergeVersion.Minor`
Expand All @@ -36,25 +51,28 @@ If we try to build from a commit that is no merge and no tag then assume `0.1.0`
* stability: final

Optional Tags (only when transitioning existing repository):

* TagOnHeadCommit.Name={semver} => overrides the version to be {semver}

Long version:
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`
`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: `alpha.{n}` where n = how many commits `develop` is in front of `masterVersionCommit.Date` ('0' padded to 4 characters)
* pre-release: `alpha.{n}` where n = how many commits `develop` is in front of
`masterVersionCommit.Date` ('0' padded to 4 characters)

Long version:
Long version:

{major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
1.2.3-alpha.645 Branch:'develop' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
Expand All @@ -63,14 +81,15 @@ Long version:

Named: `hotfix-{versionNumber}` eg `hotfix-1.2`

`branchVersion` => the SemVer extracted from `targetBranch.Name`
`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)
* pre-release: `beta{n}` where n = number of commits on branch ('0' padded to
4 characters)

Long version:
Long version:

{major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
1.2.3-beta645 Branch:'hotfix-foo' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
Expand All @@ -82,16 +101,21 @@ Long version:
* 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`
`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`.
* 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`
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:
Long version:

{major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
1.2.3-alpha2.4 Branch:'release-1.2' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
Expand All @@ -101,17 +125,19 @@ Long version:

May branch off from: `develop`
Must merge back into: `develop`
Branch naming convention: anything except `master`, `develop`, `release-{n}`, or `hotfix-{n}`.
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"
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: `alpha.feature-{n}` where n = First 8 characters of the commit SHA of the first commit

* pre-release: `alpha.feature-{n}` where n = First 8 characters of the commit
SHA of the first commit

Long version:
Long version:

{major}.{minor}.{patch}-{pre-release} Branch:'{branchName}' Sha:'{sha}'
1.2.3-alpha.feature-a682956d Branch:'feature1' Sha:'a682956dccae752aa24597a0f5cd939f93614509'
Expand All @@ -120,17 +146,21 @@ Long version:

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/`.
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: `alpha.pull{n}` where n = the pull request number ('0' padded to 4 characters)
* pre-release: `alpha.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.
**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??
How do we do release candidates?? Perhaps tag a release branch and then count
commits forward from the tag to get RC1, RC2 etc??
16 changes: 14 additions & 2 deletions docs/input/docs/git-branching-strategies/githubflow-examples.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,24 @@
# GitHubFlow Examples
---
Order: 50
Title: GitHubFlow Examples
---

## Feature branch

![GitHubFlow](img/githubflow_feature-branch.png)

## Pull requests

![GitHubFlow](img/githubflow_pull-request.png)

## Release branch
Release branches can be used in GitHubFlow as well as GitFlow. Sometimes you want to start on a large feature which may take a while to stabilise so you want to keep it off master. 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.

Release branches can be used in GitHubFlow as well as GitFlow. Sometimes you
want to start on a large feature which may take a while to stabilise so you want
to keep it off master. 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](img/githubflow_release-branch.png)

0 comments on commit 1772a1d

Please sign in to comment.