Skip to content

GitLab

gitlab issues workflow · Changes

Page history
mmclin created page: gitlab-issues-workflow authored by Mike McLin's avatar Mike McLin
Hide whitespace changes
Inline Side-by-side
gitlab-issues-workflow.markdown 0 → 100644
View page @ 29b7bde3
###### [Gitlab](gitlab) / Issues Workflow
# Gitlab Issues Workflow
This guide takes you step-by-step through our Gitlab workflow from issue to completion. We start by creating an issue on Gitlab, and then creating a development branch for the issue on Git. All development for that issue happens on that issue branch. Eventually once the issue concerns have been committed and pushed, we walk through the steps of initiating and accepting a merge request, which is the final step of the workflow.
#### Create an issue
1. Go to Gitlab project and click **Issues** from the header navigation
2. Check to see if issue already exists (check both open and closed issues)
* If an issue already exists and is **open**
1. Leave any comment that might contribute to the issue's conversation
* If an issue already exists and is **closed**
1. Re-open ticket and leave a comment explaining why there is work to be done with the issue
* If an issue does not already exist
1. Click the **New Issue** button
2. Give your issue a brief but meaningful title in the **Subject** field - e.g. `Restrict droppable area for draggable items`
3. Assign at least one label - e.g. `bug`
* If the **Label** text input doesn't have autocomplete functionality with pre-built labels, then you need to generate labels for the project (a one-time process). Go to the **Issues** section, click the **Labels** tab, and then click the **Generate** link.
4. Fill out the **Details** field and any other fields that you want to set (Assign to, Milestone).
5. Click **Submit new issue**
#### Create development branch
##### Generic Git Workflow
1. Checkout **master** branch
2. Pull changes from **origin/master**
3. Create a new issue/development branch from **master** following these naming conventions...
* Should start with a (single) main **label** for the Gitlab Issue, followed by a slash - e.g. `bug/`
* Should be a lowercased, dash-separated and a potentially shorter version of the Gitlab Issue **Subject** - e.g. `bug/restrict-droppable-for-draggables`
4. Checkout the new issue/development branch
5. Create remote branch by pushing to origin using the same branch name.
6. Begin development
##### PhpStorm Workflow
There are several ways to access the Git commands in PhpStorm. These instructions make use of the **Navigation Bar** at the top of the PhpStorm window and the **Status Bar** at the very bottom of the PhpStorm window. Make sure they are visible by enabling the **View** > **Navigation Bar** and **View** > **Status Bar** menu items.
1. Make sure you are on the **master** branch
* The right-side of the **Status Bar** at the bottom, you should see **Git: {BRANCH NAME}**
* If the **{BRANCH NAME}** is not **master** then click the branch name to open the branches popup menu. From the **Local Branches** section, choose **master -> origin/master** > **checkout**.
2. Pull changes from Gitlab (origin). Click the **Update Project** button *(has an icon that says "VCS" with a blue downward arrow below it)* located on the right side of the upper **Navigation Bar**.
3. Click the **Git: {BRANCH NAME}** menu towards the right-hand side of the **Status Bar** to reveal the **Git Branches** popup menu
4. Choose **New Branch** to create your issue/development branch and follow these naming conventions...
* Should start with a (single) main **label** for the Gitlab Issue, followed by a slash - e.g. `bug/`
* Should be a lowercased, dash-separated and a potentially shorter version of the Gitlab Issue **Subject** - e.g. `bug/restrict-droppable-for-draggables`
4. PhpStorm creates the branch and checks it out so you are now in your new branch. You should now see your newly created branch name as the selected branch in the **Status Bar**. If you don't, check it out.
5. Create a remote branch on Gitlab (origin) by opening the Terminal via the **Tools** > **Open Terminal...** menu item, and then entering this command: `git push origin {ISSUE BRANCH NAME}` where `{ISSUE BRANCH NAME}` is the name of the issue branch that you just created - e.g. `git push origin bug/restrict-droppable-for-draggables`
#### Develop, Commit, Push
##### Generic Workflow
1. Whenever development for this issue occurs, make sure you have the branch that was created for this issue checked out
2. All commits should reference the issue. Do this by placing a `#{ISSUE ID}` somewhere in the commit message - e.g. `#4: Add start() event listener that kills overlay`.
* You can also close a ticket via the commit message by starting your commit message with: `Fixes #{ISSUE ID}` or `Closes #{ISSUE ID}` - e.g. `Fixes #4: Add start() event listener that kills overlay`
* **NOTE**: You will not see these commit messages in the Issue comments until your branch has been merged into the **master**.
3. Push the branch to Gitlab (origin) using the same name for the remote branch as the local branch that was created for the issue.
4. Repeat until issue is resolved.
##### PhpStorm Workflow
1. Whenever development for this issue occurs, make sure you have the branch that was created for this issue checked out
* The right-side of the **Status Bar** at the bottom, you should see **Git: {ISSUE BRANCH NAME}**
* If the **{ISSUE BRANCH NAME}** isn't the correct branch created for the issue, then click the branch name to open the branches popup menu. From the **Local Branches** section, choose correct branch and select **checkout**.
2. Commit changes to your local repo by clicking the **Commit Changes** button *(has an icon that says "VCS" with a green upward arrow below it)* located on the right side of the upper **Navigation Bar**. All commits should reference the issue. Do this by placing a `#{ISSUE ID}` somewhere in the commit message - e.g. `#4: Add start() event listener that kills overlay`.
* You can also close a ticket via the commit message by starting your commit message with: `Fixes #{ISSUE ID}` or `Closes #{ISSUE ID}` - e.g. `Fixes #4: Add start() event listener that kills overlay`.
* **NOTE**: You will not see these commit messages in the Issue comments until your branch has been merged into the **master**.
3. After filling out your commit message, you can choose to Commit and Push, or just Commit. Just note that a **Push** is required either then or later on to have your commits show up on Gitlab.
4. When you do push, within the **Git Push** popup window you'll notice towards the bottom that it will push to the **origin** and use the same branch as your issues branch. Click the **Push** button to push your commits to Gitlab (origin).
5. Repeat until resolved.
#### Create Merge Request
1. Go to Gitlab project and click **Merge Requests** from the header navigation
2. Click the **New Merge Request** button
3. On the left-hand side choose the branch associated with the issue. On the right-hand side choose the `master` branch
4. If someone else is responsible for accepting the merge request, then it might be helpful to assign the merge request to them and use the **Description** to communicate any extra information to them.
5. Click **Submit merge request** button
#### Handling the Merge Request (Project Admin)
1. Go to Gitlab project and click **Merge Requests** from the header navigation
2. Select the merge request that you are interested in
3. Verify the code
* For simple requests, you can view the **Diff** tab below the Commits list
* For more involved merges, pull the branch down to your local repo and verify it works as expected.
4. If there are issues, add a comment to the **Discussion** tab below the Commits list. It could help to reference any people that might need to know about the reject by using the `@{USERNAME}` pattern in the comment - e.g. `@mmclin`
5. Once everything looks good, enable the **Remove source-branch** checkbox if the issue is complete and the branch is no longer needed, and then click the **Accept Merge Request** button.
\ No newline at end of file