Inca Company Gitlab How-To

We use Gitlab as an issue tracker, repository storage, and time tracking tool.

For more details on Gitlab, check out this document.

1. Milestones

A milestone is a temporary effort that includes multiple issues and has a defined finish line.

Milestones are SMART goals - Specific, Measurable, Attainable, Realistic, and Timely goals.

The purpose of milestones is to show progress on a focused group of issues.

Milestones are not used to filter issues, or to group similar issues.

For each milestone set a due date for when we expect the milestone to be completed. You have to make sure that we get complete all issues within the specified due date, so check in with the team on the status of all issues and make sure everything goes as expected. If you see there might be delays; it is your responsibility to suggest a workaround and coordinate a fix.

To see project milestones, go to ‘Projects’, pick the project, click ‘Issues’ in the left menu and select ‘Milestones’.

2. Issues

An issue is an independent task usually performed by one person. For issues, you not only indicate a due date but also select an assignee, which is a person responsible for closing the issue.

There are two basic representations for issues:

Simple list view:

and Boards View

This is the Kanban approach, which is very useful, because it visualizes your list of tasks as a process, and you can see what’s in the backlog, what’s in progress, and what’s done already.

Always create an issue for things you work on. If it is worth spending time on since that enables other people to see your work in real time and intervene if something doesn’t look right. You can always edit the description or close it when the problem changed to something different or was solved. When completing the issue, set the Done tag and let the person who created the issue check your work and close it.

Assignees

If you create an issue, you need to assign it to someone unless you want to do it yourself (in which case you should assign it to yourself).

Labels

Labels are important for everyone to understand the status of the issue without going trough the comments. Always have at least one of the following labels assigned to the issue:

• status::to do
• status::doing
• status::done
• status::on hold
• status::discussion

There are also other labels, and you can create on your own if needed.

Business-Specific Issue Labels

When creating an issue in the IncaSec/Business project it is important to use the labels outlined in this image: Business Issue Labeling Logic.

Business Issue Labeling Logic

Each business project has a set of Required labels that must be added.

Required Labels by Project

• Sales Pipeline Project
  • Priority
    
  • Status
  • Client Segment
• NTerminal Client Development Project
  • Priority
    
  • Status
  • Client Segment
• Internal Development Project
  
  • Completion

Optional Labels by Project

• You may use any additional Optional labels to help organize and filter your issues
  • Optional label examples are “Chicago”, “Time Sensitive”, or “Monthly Report Client”

Where to Put a Business Issue

Deadlines

Always put a due date to your issue so that everyone would understand the progress you make over the issue.

Time Cap label

We often need to limit the time we spend on a specific issue to make sure it doesn’t become a time sink. Unless additional details are provided, setting this label means:

• No team member can spend more than an hour per week working on this issue.
• No team member can send more than one external email per week concerning this issue.
• All time spent working on this issue needs to be recorded.

3. Creating a Branch

There are two methods of creating a new branch. The first is to define the new branch and then make edits, and the second is to make edits and committing them to a new branch.

1. Navigate to the “branches” option within the repository on the far left of your screen
2. Select New Branch
3. Give the new branch a meanighful name and choose which branch you want to create from (default and most commonly being master)

Alternatively, you can create a new branch when editing a file within the master branch.

1. Edit the file within the master branch
2. When you are ready to commit, change to target branch field to the name of the new branch you want to create.
3. When you type in a new branch name, you can select to start a merge request for the branch, although this step is not necessary

NOTE: you cannot use the target branch field to commit changes to a pre-existing branch unless you access the file from that branch.

You can then navigate to this branch and compare it to others in the “Active branches” section after selecting “Branches” on the left of your screen.

Making Changes Within a Branch

General good practice involves making all the related changes in a single branch (rather than to individual branches per change). To make changes to the new branch you have created, navigate to the project repository and change the branch you want to edit in the top left corner.

Adding a File to a Branch

New files can also be added to the branch. To add a new file:

1. Go to the branch
2. Select the plus icon in the path at the top of the window
3. Create new file type based on project requirements
4. Add content
5. Commit changes to the target branch

4. Merge Requests

It’s a good practice to create a merge request as soon as you created your new branch and assign the person responsible for merging, approvers, and appropriate labels. This serves as a heads-up for everyone involved and allows them to comment on your work in progress.

• 1 merge request and 1 branch per meaningful and complete update. No need to create separate ones for every commit within one logical update.
• Don’t forget to use the WIP tag if you want to prevent people from merging your work into the master branch before it’s done.

To create a merge request:

1. Select after navigating to “Merge Requests” on the left of your screen
2. The Source branch refers to the branch where your edits are stored, while the target branch refers to the branch that you want to integrate these changes to. When you have selected your branches press the Compare branches and continue button.

1. You may add a title to the merge request and description on the following page. If your merge request is not ready, start it with the WIP: tag. It is good practice to include information about what the changes within the merge are related to. Giving a quick description and linking any related issues or outside documents is always helpful.
2. Merge requests require that an individual on the project is Assigned to check the request and execute the merge. If the WIP: tag remains on the merge request, the initiator of the request must resolve or remove this tag for Assigned individuals to execute the merge.
3. Always define the stage of development for your merge request. Make it easy for everyone to follow on your progress.

• Alternatively, use Gitlab Web IDE or IntelliJ IDEA. Just don’t forget to commit often to show others your progress and make it easier for your reviewers to merge when you are done. No one likes to see thousands lines of code to review at the end of the month.

---

Make sure to review Inca Best Practices if you haven’t already.