diff --git a/doc/workflow/ci_mr.png b/doc/workflow/ci_mr.png new file mode 100644 index 0000000000000000000000000000000000000000..2338fe2da055f20f689080a6e1ae144a18e1bc45 Binary files /dev/null and b/doc/workflow/ci_mr.png differ diff --git a/doc/workflow/close_issue_mr.png b/doc/workflow/close_issue_mr.png new file mode 100644 index 0000000000000000000000000000000000000000..a136d642e125a782c8058417ff808b98159c0899 Binary files /dev/null and b/doc/workflow/close_issue_mr.png differ diff --git a/doc/workflow/git_pull.png b/doc/workflow/git_pull.png new file mode 100644 index 0000000000000000000000000000000000000000..7d47064eb14176ccc23e472cbf1d9ea34f90d91f Binary files /dev/null and b/doc/workflow/git_pull.png differ diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md index 546fd35c9e1cb8f051aab92f5e7377a844f78c40..883da88abe86e94258cc66e61d8d3aa404c095be 100644 --- a/doc/workflow/gitlab_flow.md +++ b/doc/workflow/gitlab_flow.md @@ -95,7 +95,7 @@ In this flow it is not common to have a production branch (or git flow master br # Merge/pull requests with GitLab flow -![Merge request with line comments]() Merge or pull requests are created in a git management application and ask an assigned person to merge two branches. + 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 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. @@ -118,7 +118,7 @@ So if you want to merge it into a protected branch you assign it to someone with # Issues with GitLab flow -![Merge request with the branch name 15-require-a-password-to-change-it and assignee field shown]() GitLab flow is a way to make the relation between the code and the issue tracker more transparent. + 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. 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 +150,7 @@ It is possible that one feature branch solves more than one issue. # Linking and closing issues from merge requests -![Merge request showing the linked issues that will be closed]() Linking to the issue can happen by mentioning them from commit messages (fixes #14, closes #67, etc.) or from the merge request description. + 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. And the merge request shows the linked issues. These issues are closed once code is merged into the default branch. @@ -161,7 +161,7 @@ If you have an issue that spans across multiple repositories, the best thing is # Squashing commits with rebase -![Vim screen showing the rebase view]() With git you can use an interactive rebase (rebase -i) to squash multiple commits into one and reorder them. + 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. However you should never rebase commits you have pushed to a remote server. Somebody can have referred to the commits or cherry-picked them. @@ -185,7 +185,7 @@ Git management software will always create a merge commit when you accept a merg # Do not order commits with rebase -![List of sequencial merge commits]() With git you can also rebase your feature branch commits to order them after the commits on the master branch. + 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. 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. @@ -220,13 +220,13 @@ If you rebase code the history is incorrect, and there is no way for tools to re # Voting on merge requests -![Voting slider in GitLab]() It is common to voice approval or disapproval by using +1 or -1 emoticons. + 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. 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 -![Remove checkbox for branch in merge requests]() We recommend that people push their feature branches frequently, even when they are not ready for review yet. + 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. 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. @@ -238,7 +238,7 @@ When you reopen an issue you need to create a new merge request. # Committing often and with the right message -![Good and bad commit message]() We recommend to commit early and often. + We recommend to commit early and often. 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. This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share. @@ -252,7 +252,7 @@ To see more information about the formatting of commit messages please see this # Testing before merging -![Merge requests showing the test states, red, yellow and green]() In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only. + 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. 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. @@ -267,7 +267,7 @@ If you have long lived feature branches that last for more than a few days you s # Merging in other code -![Shell output showing git pull output]() When initiating a feature branch, always start with an up to date master to branch off from. + 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 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. diff --git a/doc/workflow/good_commit.png b/doc/workflow/good_commit.png new file mode 100644 index 0000000000000000000000000000000000000000..3737a0266445e6714980a693a7b031e678ad841a Binary files /dev/null and b/doc/workflow/good_commit.png differ diff --git a/doc/workflow/merge_commits.png b/doc/workflow/merge_commits.png new file mode 100644 index 0000000000000000000000000000000000000000..757b589d0dbb71c56b56905eb9fb1af895d859b6 Binary files /dev/null and b/doc/workflow/merge_commits.png differ diff --git a/doc/workflow/merge_request.png b/doc/workflow/merge_request.png new file mode 100644 index 0000000000000000000000000000000000000000..fde3ff5c854f877e2a621f6b15ee1c6ed7ac5a8d Binary files /dev/null and b/doc/workflow/merge_request.png differ diff --git a/doc/workflow/mr_inline_comments.png b/doc/workflow/mr_inline_comments.png new file mode 100644 index 0000000000000000000000000000000000000000..e851b95bcefff033e075d76221c29f2541a38245 Binary files /dev/null and b/doc/workflow/mr_inline_comments.png differ diff --git a/doc/workflow/rebase.png b/doc/workflow/rebase.png new file mode 100644 index 0000000000000000000000000000000000000000..ef82c834755c7b3e2c53145418c461044344f430 Binary files /dev/null and b/doc/workflow/rebase.png differ diff --git a/doc/workflow/remove_checkbox.png b/doc/workflow/remove_checkbox.png new file mode 100644 index 0000000000000000000000000000000000000000..3e247d381556a2f1f05ea8649105885d53174cd5 Binary files /dev/null and b/doc/workflow/remove_checkbox.png differ diff --git a/doc/workflow/voting_slider.png b/doc/workflow/voting_slider.png new file mode 100644 index 0000000000000000000000000000000000000000..4c660ef95937c66924a2f01373cc4efed4eae831 Binary files /dev/null and b/doc/workflow/voting_slider.png differ