Home / 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.

Read This!

The following is our generic Issue Workflow. You should always check to see if the project you are contributing to has a CONTRIBUTING.md file in the root directory of the project's Gitlab Files section. If so, that project might have special concerns when dealing with issues workflow. For example, the project might require a regression test to be created with each issue, or perhaps the project has Continuous Integration implemented (possibly via Jenkins) and special steps need to be taken to make sure you are following the prescribed workflow for that project.

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 either feature/, release/ or hotfix/
   • Should be a lowercased, dash-separated and a potentially shorter version of the Gitlab Issue Subject - e.g. hotfix/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

This assumes that you have already installed the PhpStorm Gitflow plugin. All interaction with Gitflow is done via the Gitflow menu towards the right-side of the PhpStorm Status Bar, which is located at the bottom of the screen. If you do not see your status bar, make sure to enable the View > Status Bar option in your PhpStorm menu.

1. If the Gitflow menu says "No Gitflow", install Gitflow for the project
   1. Make sure your working directory is clean (you don't have any files that are being tracked and have been modified, but not committed).
   2. From the Gitflow menu, choose Init Repo
   3. Click the OK button accepting the default settings
      • Gitflow has created a develop branch for you, and checked it out
2. Either track an existing Gitlab issue branch, or create one
   • If an issue branch already exists on Gitlab, choose either Track Feature, Track Release or Track Hotfix from the Gitflow menu. You can now skip to the Develop, Commit, Push section.

• If no branch for the issue exists on Gitlab, choose either Start Feature, Start Release or Start Hotfix from the Gitflow menu. * The type of branch you want to start should be consistent with type of issue you are trying to complete. If the Gitlab issue has a label of bug, then you would choose Start Hotfix, if the Gitlab issue has a label of enhancement, then you would choose Start Feature and so on.

3. Name the new branch (Gitflow will prepend either feature/, release/ or hotfix/ to the branch name for you)
   • The name should be a lowercased, dash-separated and a potentially shorter version of the Gitlab Issue Subject - e.g. restrict-droppable-for-draggables
4. Gitflow created the branch (based on your develop branch), and checked it out
5. Create a remote branch on Gitlab by choosing Publish {TYPE} from the Gitflow menu. This will also link your local issue branch to the remote one just just created.

Develop, Commit, Push

Generic Git 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.
   • 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.
5. Pull from origin/master and merge into your local issue branch and then push the issue branch one more time to the origin (Gitlab) before moving on to "creating a merge request" step.

PhpStorm Workflow

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. 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.
   • 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.
6. Once you are completely done you will want to pull from origin/master and push one final time.
   1. Open the Git {ISSUE BRANCH NAME} menu in the bottom status bar and choose master -> origin/master > merge. This will add any changes that have been pushed to the project to your branch.
   2. Push the issue branch to the origin (Gitlab) by choosing VCS > Git > Push... from the top PhpStorm menu.
      • Productivity Tip - You can also push using the VCS > VCS Operations Popup... which also has a keyboard shortcut that you should learn (CONTROL + V).
7. Choose Finish {TYPE} from the Gitflow menu in the bottom status bar.
   • This will switch back to your develop branch, merge in the changes from the issue branch, and then delete your local issue branch.

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.