From fd7579464952089302fe2de1c37f66552a20c302 Mon Sep 17 00:00:00 2001 From: Pietro Grandi Date: Wed, 1 Mar 2017 11:09:19 +0100 Subject: [PATCH 1/3] Update Git workflow Master is no longer the main branch and branches are never deleted --- style/git/README.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/style/git/README.md b/style/git/README.md index aa54956..de5b99b 100644 --- a/style/git/README.md +++ b/style/git/README.md @@ -4,9 +4,9 @@ ### Content The commit message serves to provide a technical description of the change introduced by its commit. It should be possible to look at a commit message in -combination with its diff and quickly understand **what** was changed **where**, -**how** it was changed and **why**. Simple changes sometimes speak for -themselves. Complex changes need more explanation. +combination with its diff and quickly understand **what** was changed +**where**, **how** it was changed and **why**. Simple changes sometimes speak +for themselves. Complex changes need more explanation. * Commits are a form of documentation * Time spent writing costs less than the time spent reading @@ -31,7 +31,7 @@ The commit message body describes the current state (**why**): * Use present tense, e.g. "Foo does not work" * Avoid past tense, e.g. "Foo did not work" -It describes what the the commit does to change the current state (**what**): +It describes what the commit does to change the current state (**what**): * Match the subject and use imperative mood "Fix foo by doing bar" * Or use a descriptive tone "This fixes foo by doing bar" @@ -118,12 +118,12 @@ Furthermore: commit. ## Branches -1. Branch `master` contains the latest stable release +1. Branch `next` contains the latest stable release 2. Integration branches are namespaced `integration/` 3. Individual words in branch names are separated by hyphen-minus (`-`) ### Personal branches -1. Personal branches are namespaced `/` where `` is your firstname +1. Personal branches are namespaced `/` where `` is your first name or known nickname. 2. It is a good idea to push even unfinished work to your personal namespace frequently. @@ -150,9 +150,6 @@ Furthermore: 1. Makes the history unnecessarily complex 2. Personal branches should be simple and short-lived -5. Delete remote branch when it has been merged - 1. Superfluous entropy serves no purpose - ## Tags 1. All tags are annotated (`-a`) 2. Individual words in tags are separated by hyphen-minus (`-`) From 6daa9c6ac6cf6f3f0a4d7ecef312f516c11868da Mon Sep 17 00:00:00 2001 From: Pietro Grandi Date: Wed, 1 Mar 2017 12:02:01 +0100 Subject: [PATCH 2/3] Update merge request process References to Jira, new labels, and new branch to be used. --- process/merge_requests/README.md | 84 ++++++++++++++------------------ 1 file changed, 36 insertions(+), 48 deletions(-) diff --git a/process/merge_requests/README.md b/process/merge_requests/README.md index 826341a..75242b8 100644 --- a/process/merge_requests/README.md +++ b/process/merge_requests/README.md @@ -1,13 +1,8 @@ # Merge requests ## Introduction Since introducing GitLab to our workflow, we've been using it as our primary -tool for reviewing code. -While issues still reside in Redmine and the actual merging/deploying is handled -outside of GitLab, commenting and discussing code is handled through GitLab. - -While there has been discussion about altering the workflow to utilize GitLab's -various features more extensively, for now you should only consider it being -something that rests on top of your everyday work in Redmine. +tool for reviewing code. While issues still reside in JIRA the actual merging, +deploying, commenting and discussing code is handled through GitLab. ## Prerequisite The following instructions assume you have a working GitLab account. If you @@ -15,10 +10,11 @@ don't yet have access to the web interface of GitLab, contact Operations. ## Lifecycle of a merge request ### Creation procedure -Let's assume you've worked on an issue enough to set the status to "Feedback", -which would put it into the feedback queue. +Let's assume you've worked on an issue enough to set the status to review, +which would put it into the review's queue. + +Before you set the status to review, make sure that there's a Merge Request -Before you set the status to "Feedback", make sure that there's a Merge Request (henceforth referred to as "MR") available in GitLab. These are the steps necessary: @@ -26,56 +22,54 @@ These are the steps necessary: 1. Log in to GitLab. 2. When logged in, you should arrive at the Dashboard (as written in the top left). Click "Projects" in the menu to the left. -3. Choose the project which you wish to submit a MR for. Most of the time, this - will be "sparkle". +3. Choose the project which you wish to submit a MR for. 4. Click "Merge Requests" in the menu to the left. 5. Click the green "New Merge Request" button, located in the top right part of the page. 6. Here you'll need to provide the **source** branch and the **target** branch. - The source branch should be the branch which you wish to have reviewed, while - the target branch should be what you want to merge into. - Unless you've been asked to set it to something else, you'll want the target - branch to be set to `master`. + The source branch should be the branch which you wish to have reviewed, + while the target branch should be what you want to merge into. Unless + you've been asked to set it to something else, you'll want the target branch + to be set to `next`. 7. Press the blue "Compare branches" button. 8. Enter title and description, following the guidelines written in the **Title and Description guidelines** section. - Set no label, this will be done by someone else. - Set no assignee, unless you've been asked to. 9. At this point you can review the MR one final time before pressing the "Submit merge request" button. -This should take you to the page with the now created MR. -All that is necessary from here is to post a link to the MR over in the -corresponding Redmine issue. +This should take you to the page with the now created MR. + +All that is necessary from here is to **add a link to the MR in the JIRA ticket**. #### Title and Description guidelines The title should always look something like this: #12345: Adjust constant in warpcore configuration to prevent overheating -Notice the issue number at the start, including the `#` character. This text -will automatically be linked to the Redmine issue, which makes it easy to access -the discussion in Redmine. -Following the issue number should be general description of what the MR changes. +Notice the issue number at the start, including the # character. Following the +issue number should be general description of what the MR changes. The description should include the following: -* What the MR changes, being a bit more descriptive than the title. -* If there's something you're unsure of how it should be done, point this out so +* A direct link to the JIRA ticket, in the form of: `refs [#12345](https://jira.server/12345)` +* What the MR changes, being a bit more descriptive than the title. If there's +* something you're unsure of how it should be done, point this out so + that the reviewer can help you out. * If necessary, include information that would help the reviewer understand *why* you made certain changes. This information should already be present in the form of [well written commit messages](../../style/git), but it doesn't hurt including this in the MR description. * If there are parts of the changeset that can be ignored (you added a library - to vendor, resulting in thousands of lines of code), you should point this out - so the reviewer doesn't waste time sifting through vendor code. + to vendor, resulting in thousands of lines of code), you should point this + out so the reviewer doesn't waste time sifting through vendor code. * If the merge will require some additional deploy instructions, include these so that they too can be reviewed. + ### Working with merge requests #### Git -The process of working and commiting when working in conjunction with MRs +The process of working and committing when working in conjunction with MRs doesn't differ much from how work has been handled when we only used Redmine, but there's one major difference: @@ -85,11 +79,14 @@ use fixup commits that are squashed by the end of the life cycle of the MR. What does this mean? Let's say you've submitted your MR and the reviewer wants you to change -something in a previous commit. If you previously had the habit of creating -a commit, rebasing and squashing right away: refrain from doing so. The -preferred way of doing things in this system [is to create fixup commits][fixup] -that are squashed at the very end of the life cycle of the MR, so pretty much -when the reviewer approves the MR for merging. +something in a previous commit. + +If you previously had the habit of creating a commit, rebasing and squashing +right away: refrain from doing so. The preferred way of doing things in this +system [is to create fixup commits][fixup] that are squashed at the very end of +the life cycle of the MR, so pretty much when the reviewer approves the MR for +merging. The rebase process would be done by the author when asked from the +reviewer, depending on the MR's complexity. [fixup]: http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html @@ -99,8 +96,8 @@ If there's no need to rewrite history, for instance if you start adding new features after the MR is submitted, just keep working as you always have. #### The merge request interface -If you make an adjustment (e.g. to address a comment that was left by -a reviewer) and push the resulting code, this will immediately be reflected in +If you make an adjustment (e.g. to address a comment that was left by a +reviewer) and push the resulting code, this will immediately be reflected in the MR. This way, the reviewer will always see the latest version of the branch in the MR. @@ -119,21 +116,12 @@ become easier to if you surround it with backticks. [GFMD]: http://doc.gitlab.com/ce/markdown/markdown.html ### Closing a merge request -When the reviewer considers the code ready to merge, he'll say so, and a label -with the name `ready-to-merge` will be applied, indicating that the branch is -ready to merge and deploy. -Don't worry about applying the label, one of the developers with merge/admin -rights will handle it. - -Once it has been said in the MR that it's ready for merging, write the same in -Redmine (if the reviewer hasn't done it already). - Do not close the MR, it will be closed automatically when the branch is merged -into `master` (or whatever other branch was set as the target branch). +into `next` (or whatever other branch was set as the target branch). ## Finding merge requests As stated at the end of the "Creation procedure" section, if an issue in -Redmine has code that should be reviewed, a link to the corresponding MR in +JIRA has code that should be reviewed, a link to the corresponding MR in GitLab *must* be posted. This link will probably be the easiest way to find the MR in GitLab. From f2893ced9c1934825b379f026b00d9ae5e296a03 Mon Sep 17 00:00:00 2001 From: Pietro Grandi Date: Tue, 4 Apr 2017 15:03:01 +0200 Subject: [PATCH 3/3] Fix as per revision --- process/merge_requests/README.md | 2 -- style/git/README.md | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/process/merge_requests/README.md b/process/merge_requests/README.md index 75242b8..f6a03e0 100644 --- a/process/merge_requests/README.md +++ b/process/merge_requests/README.md @@ -14,7 +14,6 @@ Let's assume you've worked on an issue enough to set the status to review, which would put it into the review's queue. Before you set the status to review, make sure that there's a Merge Request - (henceforth referred to as "MR") available in GitLab. These are the steps necessary: @@ -54,7 +53,6 @@ The description should include the following: * A direct link to the JIRA ticket, in the form of: `refs [#12345](https://jira.server/12345)` * What the MR changes, being a bit more descriptive than the title. If there's * something you're unsure of how it should be done, point this out so - that the reviewer can help you out. * If necessary, include information that would help the reviewer understand *why* you made certain changes. This information should already be present in diff --git a/style/git/README.md b/style/git/README.md index de5b99b..709b017 100644 --- a/style/git/README.md +++ b/style/git/README.md @@ -118,7 +118,7 @@ Furthermore: commit. ## Branches -1. Branch `next` contains the latest stable release +1. Branch `master` contains the latest stable release 2. Integration branches are namespaced `integration/` 3. Individual words in branch names are separated by hyphen-minus (`-`)