🏠 / 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
5. 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.
6. 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.