BigW Consortium Gitlab

Skip to content

G
gitlab-ce
Commit 221210a5 by Sytse Sijbrandij
Options

Merge branch 'imp-gitflow' into 'master'

Improve gitflow article See merge request !195
parents cc778b0a 17ad28f3
Showing with 51 additions and 17 deletions
doc/workflow/gitlab_flow.md
...@@ -11,13 +11,17 @@ Organizations coming to git from other version control systems frequently find i ...@@ -11,13 +11,17 @@ Organizations coming to git from other version control systems frequently find i
This article describes the GitLab flow that integrates the git workflow with an issue tracking system. This article describes the GitLab flow that integrates the git workflow with an issue tracking system.
It offers a simple, transparent and effective way to work with git. It offers a simple, transparent and effective way to work with git.
![Four stages (working copy, index, local repo, remote repo) and three steps between them]() When converting to git you have to get used to the fact that there are three steps before a commit is shared with colleagues. ![Four stages (working copy, index, local repo, remote repo) and three steps between them](four_stages.png)
When converting to git you have to get used to the fact that there are three steps before a commit is shared with colleagues.
Most version control systems have only step, committing from the working copy to a shared server. Most version control systems have only step, committing from the working copy to a shared server.
In git you add files from the working copy to the staging area. After that you commit them to the local repo. In git you add files from the working copy to the staging area. After that you commit them to the local repo.
The third step is pushing to a shared remote repository. The third step is pushing to a shared remote repository.
After getting used to these three steps the branching model becomes the challenge. After getting used to these three steps the branching model becomes the challenge.
![Multiple long running branches and merging in all directions]() Since many organizations new to git have no conventions how to work with it, it can quickly become a mess. ![Multiple long running branches and merging in all directions](messy_flow.png)
Since many organizations new to git have no conventions how to work with it, it can quickly become a mess.
The biggest problem they run into is that many long running branches that each contain part of the changes are around. The biggest problem they run into is that many long running branches that each contain part of the changes are around.
People have a hard time figuring out which branch they should develop on or deploy to production. People have a hard time figuring out which branch they should develop on or deploy to production.
Frequently the reaction to this problem is to adopt a standardized pattern such as [git flow](http://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow]() Frequently the reaction to this problem is to adopt a standardized pattern such as [git flow](http://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow]()
...@@ -25,7 +29,9 @@ We think there is still room for improvement and will detail a set of practices ...@@ -25,7 +29,9 @@ We think there is still room for improvement and will detail a set of practices
# Git flow and its problems # Git flow and its problems
[![Git Flow timeline by Vincent Driessen, used with persmission](http://nvie.com/img/2009/12/Screen-shot-2009-12-24-at-11.32.03.png)](http://nvie.com/posts/a-successful-git-branching-model/) Git flow was one of the first proposals to use git branches and it has gotten a lot of attention. [![Git Flow timeline by Vincent Driessen, used with persmission](gitdashflow.png)
Git flow was one of the first proposals to use git branches and it has gotten a lot of attention.
It advocates a master branch and a separate develop branch as well as supporting branches for features, releases and hotfixes. It advocates a master branch and a separate develop branch as well as supporting branches for features, releases and hotfixes.
The development happens on the develop branch, moves to a release branch and is finally merged into the master branch. The development happens on the develop branch, moves to a release branch and is finally merged into the master branch.
Git flow is a well defined standard but its complexity introduces two problems. Git flow is a well defined standard but its complexity introduces two problems.
...@@ -44,7 +50,9 @@ And doing releases doesn't automatically mean also doing hotfixes. ...@@ -44,7 +50,9 @@ And doing releases doesn't automatically mean also doing hotfixes.
# GitHub flow as a simpler alternative # GitHub flow as a simpler alternative
![Master branch with feature branches merged in](github_flow.png) In reaction to git flow a simpler alternative was detailed, [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html). ![Master branch with feature branches merged in](github_flow.png)
In reaction to git flow a simpler alternative was detailed, [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html).
This flow has only feature branches and a master branch. This flow has only feature branches and a master branch.
This is very simple and clean, many organizations have adopted it with great success. This is very simple and clean, many organizations have adopted it with great success.
Atlassian recommends [a similar strategy](http://blogs.atlassian.com/2014/01/simple-git-workflow-simple/) although they rebase feature branches. Atlassian recommends [a similar strategy](http://blogs.atlassian.com/2014/01/simple-git-workflow-simple/) although they rebase feature branches.
...@@ -54,7 +62,9 @@ With GitLab flow we offer additional guidance for these questions. ...@@ -54,7 +62,9 @@ With GitLab flow we offer additional guidance for these questions.
# Production branch with GitLab flow # Production branch with GitLab flow
![Master branch and production branch with arrow that indicate deployments](production_branch.png) GitHub flow does assume you are able to deploy to production every time you merge a feature branch. ![Master branch and production branch with arrow that indicate deployments](production_branch.png)
GitHub flow does assume you are able to deploy to production every time you merge a feature branch.
This is possible for SaaS applications but are many cases where this is not possible. This is possible for SaaS applications but are many cases where this is not possible.
One would be a situation where you are not in control of the exact release moment, for example an iOS application that needs to pass AppStore validation. One would be a situation where you are not in control of the exact release moment, for example an iOS application that needs to pass AppStore validation.
Another example is when you have deployment windows (workdays from 10am to 4pm when the operations team is at full capacity) but you also merge code at other times. Another example is when you have deployment windows (workdays from 10am to 4pm when the operations team is at full capacity) but you also merge code at other times.
...@@ -68,7 +78,9 @@ This flow prevents the overhead of releasing, tagging and merging that is common ...@@ -68,7 +78,9 @@ This flow prevents the overhead of releasing, tagging and merging that is common
# Environment branches with GitLab flow # Environment branches with GitLab flow
![Multiple branches with the code cascading from one to another](environment_branches.png) It might be a good idea to have an environment that is automatically updated to the master branch. ![Multiple branches with the code cascading from one to another](environment_branches.png)
It might be a good idea to have an environment that is automatically updated to the master branch.
Only in this case, the name of this environment might differ from the branch name. Only in this case, the name of this environment might differ from the branch name.
Suppose you have a staging environment, a pre-production environment and a production environment. Suppose you have a staging environment, a pre-production environment and a production environment.
In this case the master branch is deployed on staging. When someone wants to deploy to pre-production they create a merge request from the master branch to the pre-production branch. In this case the master branch is deployed on staging. When someone wants to deploy to pre-production they create a merge request from the master branch to the pre-production branch.
...@@ -81,7 +93,9 @@ An 'extreme' version of environment branches are setting up an environment for e ...@@ -81,7 +93,9 @@ An 'extreme' version of environment branches are setting up an environment for e
# Release branches with GitLab flow # Release branches with GitLab flow
![Master and multiple release branches that vary in length with cherrypicks from master](release_branches.png) Only in case you need to release software to the outside world you need to work with release branches. ![Master and multiple release branches that vary in length with cherrypicks from master](release_branches.png)
Only in case you need to release software to the outside world you need to work with release branches.
In this case, each branch contains a minor version (2-3-stable, 2-4-stable, etc.). In this case, each branch contains a minor version (2-3-stable, 2-4-stable, etc.).
The stable branch uses master as a starting point and is created as late as possible. The stable branch uses master as a starting point and is created as late as possible.
By branching as late as possible you minimize the time you have to apply bugfixes to multiple branches. By branching as late as possible you minimize the time you have to apply bugfixes to multiple branches.
...@@ -95,7 +109,9 @@ In this flow it is not common to have a production branch (or git flow master br ...@@ -95,7 +109,9 @@ In this flow it is not common to have a production branch (or git flow master br
# Merge/pull requests with GitLab flow # Merge/pull requests with GitLab flow
![Merge request with line comments](mr_inline_comments.png) Merge or pull requests are created in a git management application and ask an assigned person to merge two branches. ![Merge request with line comments](mr_inline_comments.png)
Merge or pull requests are created in a git management application and ask an assigned person to merge two branches.
Tools such as GitHub and Bitbucket choose the name pull request since the first manual action would be to pull the feature branch. Tools such as GitHub and Bitbucket choose the name pull request since the first manual action would be to pull the feature branch.
Tools such as GitLab and Gitorious choose the name merge request since that is the final action that is requested of the assignee. Tools such as GitLab and Gitorious choose the name merge request since that is the final action that is requested of the assignee.
In this article we'll refer to them as merge requests. In this article we'll refer to them as merge requests.
...@@ -118,7 +134,9 @@ So if you want to merge it into a protected branch you assign it to someone with ...@@ -118,7 +134,9 @@ So if you want to merge it into a protected branch you assign it to someone with
# Issues with GitLab flow # Issues with GitLab flow
![Merge request with the branch name 15-require-a-password-to-change-it and assignee field shown](merge_request.png) GitLab flow is a way to make the relation between the code and the issue tracker more transparent. ![Merge request with the branch name 15-require-a-password-to-change-it and assignee field shown](merge_request.png)
GitLab flow is a way to make the relation between the code and the issue tracker more transparent.
Any significant change to the code should start with an issue where the goal is described. Any significant change to the code should start with an issue where the goal is described.
Having a reason for every code change is important to inform everyone on the team and to help people keep the scope of a feature branch small. Having a reason for every code change is important to inform everyone on the team and to help people keep the scope of a feature branch small.
...@@ -150,7 +168,9 @@ It is possible that one feature branch solves more than one issue. ...@@ -150,7 +168,9 @@ It is possible that one feature branch solves more than one issue.
# Linking and closing issues from merge requests # Linking and closing issues from merge requests
![Merge request showing the linked issues that will be closed](close_issue_mr.png) Linking to the issue can happen by mentioning them from commit messages (fixes #14, closes #67, etc.) or from the merge request description. ![Merge request showing the linked issues that will be closed](close_issue_mr.png)
Linking to the issue can happen by mentioning them from commit messages (fixes #14, closes #67, etc.) or from the merge request description.
In GitLab this creates a comment in the issue that the merge requests mentions the issue. In GitLab this creates a comment in the issue that the merge requests mentions the issue.
And the merge request shows the linked issues. And the merge request shows the linked issues.
These issues are closed once code is merged into the default branch. These issues are closed once code is merged into the default branch.
...@@ -161,7 +181,9 @@ If you have an issue that spans across multiple repositories, the best thing is ...@@ -161,7 +181,9 @@ If you have an issue that spans across multiple repositories, the best thing is
# Squashing commits with rebase # Squashing commits with rebase
![Vim screen showing the rebase view](rebase.png) With git you can use an interactive rebase (rebase -i) to squash multiple commits into one and reorder them. ![Vim screen showing the rebase view](rebase.png)
With git you can use an interactive rebase (rebase -i) to squash multiple commits into one and reorder them.
This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical. This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical.
However you should never rebase commits you have pushed to a remote server. However you should never rebase commits you have pushed to a remote server.
Somebody can have referred to the commits or cherry-picked them. Somebody can have referred to the commits or cherry-picked them.
...@@ -185,7 +207,9 @@ Git management software will always create a merge commit when you accept a merg ...@@ -185,7 +207,9 @@ Git management software will always create a merge commit when you accept a merg
# Do not order commits with rebase # Do not order commits with rebase
![List of sequential merge commits](merge_commits.png) With git you can also rebase your feature branch commits to order them after the commits on the master branch. ![List of sequential merge commits](merge_commits.png)
With git you can also rebase your feature branch commits to order them after the commits on the master branch.
This prevents creating a merge commit when merging master into your feature branch and creates a nice linear history. This prevents creating a merge commit when merging master into your feature branch and creates a nice linear history.
However, just like with squashing you should never rebase commits you have pushed to a remote server. However, just like with squashing you should never rebase commits you have pushed to a remote server.
This makes it impossible to rebase work in progress that you already shared with your team which is something we recommend. This makes it impossible to rebase work in progress that you already shared with your team which is something we recommend.
...@@ -220,13 +244,17 @@ If you rebase code the history is incorrect, and there is no way for tools to re ...@@ -220,13 +244,17 @@ If you rebase code the history is incorrect, and there is no way for tools to re
# Voting on merge requests # Voting on merge requests
![Voting slider in GitLab](voting_slider.png) It is common to voice approval or disapproval by using +1 or -1 emoticons. ![Voting slider in GitLab](voting_slider.png)
It is common to voice approval or disapproval by using +1 or -1 emoticons.
In GitLab the +1 and -1 are aggregated and shown at the top of the merge request. In GitLab the +1 and -1 are aggregated and shown at the top of the merge request.
As a rule of thumb anything that doesn't have two times more +1's than -1's is suspect and should not be merged yet. As a rule of thumb anything that doesn't have two times more +1's than -1's is suspect and should not be merged yet.
# Pushing and removing branches # Pushing and removing branches
![Remove checkbox for branch in merge requests](remove_checkbox.png) We recommend that people push their feature branches frequently, even when they are not ready for review yet. ![Remove checkbox for branch in merge requests](remove_checkbox.png)
We recommend that people push their feature branches frequently, even when they are not ready for review yet.
By doing this you prevent team members from accidentally starting to work on the same issue. By doing this you prevent team members from accidentally starting to work on the same issue.
Of course this situation should already be prevented by assigning someone to the issue in the issue tracking software. Of course this situation should already be prevented by assigning someone to the issue in the issue tracking software.
However sometimes one of the two parties forgets to assign someone in the issue tracking software. However sometimes one of the two parties forgets to assign someone in the issue tracking software.
...@@ -238,7 +266,9 @@ When you reopen an issue you need to create a new merge request. ...@@ -238,7 +266,9 @@ When you reopen an issue you need to create a new merge request.
# Committing often and with the right message # Committing often and with the right message
![Good and bad commit message](good_commit.png) We recommend to commit early and often. ![Good and bad commit message](good_commit.png)
We recommend to commit early and often.
Each time you have a functioning set of tests and code a commit can be made. Each time you have a functioning set of tests and code a commit can be made.
The advantage is that when an extension or refactor goes wrong it is easy to revert to a working version. The advantage is that when an extension or refactor goes wrong it is easy to revert to a working version.
This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share. This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share.
...@@ -252,7 +282,9 @@ To see more information about the formatting of commit messages please see this ...@@ -252,7 +282,9 @@ To see more information about the formatting of commit messages please see this
# Testing before merging # Testing before merging
![Merge requests showing the test states, red, yellow and green](ci_mr.png) In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only. ![Merge requests showing the test states, red, yellow and green](ci_mr.png)
In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only.
Developers had to ensure their code did not break the master branch. Developers had to ensure their code did not break the master branch.
When using GitLab flow developers create their branches from this master branch so it is essential it is green. When using GitLab flow developers create their branches from this master branch so it is essential it is green.
Therefore each merge request must be tested before it is accepted. Therefore each merge request must be tested before it is accepted.
...@@ -267,7 +299,9 @@ If you have long lived feature branches that last for more than a few days you s ...@@ -267,7 +299,9 @@ If you have long lived feature branches that last for more than a few days you s
# Merging in other code # Merging in other code
![Shell output showing git pull output](git_pull.png) When initiating a feature branch, always start with an up to date master to branch off from. ![Shell output showing git pull output](git_pull.png)
When initiating a feature branch, always start with an up to date master to branch off from.
If you know beforehand that your work absolutely depends on another branch you can also branch from there. If you know beforehand that your work absolutely depends on another branch you can also branch from there.
If you need to merge in another branch after starting explain the reason in the merge commit. If you need to merge in another branch after starting explain the reason in the merge commit.
If you have not pushed your commits to a shared location yet you can also rebase on master or another feature branch. If you have not pushed your commits to a shared location yet you can also rebase on master or another feature branch.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment