Git(Lab) workflow

Access

In case you need access to a certain repo, consider applying for a role that provides access to the repos you need through the dcbot.

Committing Code

At d-centralize, it’s highly preferred to create clean commits.

Creating clean commits saves both the author and the code reviewer time and makes it more likely the commit will get merged.

Do:

1. Keep the changes small.
2. Update documentation to match the changes.
3. Add tests that would fail in the old situation, but succeed in the new situation. This is especially relevant if the change doesn’t decrease test coverage.
4. Consider using git add -p. This will allow the committer to only stage and commit partial file changes.
5. Consider squashing your commits if you went on a trial & error spree. It’s probably not useful to anyone seeing that.
6. Adhere to the commit message conventions as described in Commit messages.
7. Creating an issue is not always required. If the code change is small consider creating only a merge request.

Don’t:

1. Add unrelated changes. This makes the change harder to follow for the reviewer and causes potential merge conflicts.

Branching

1. As soon as you clone a repository that you want to work on, it is essential to create a new branch and every upcoming change commit and push onto it.

2. Unless you have a good reason to deviate, it makes sense to branch off your branch from the main branch.

3. You’re free to name the branch yourself, but it’s recommended to prefix the name with an issue number so Gitlab streamlines the creation of merge requests for you.

4. Once you have completed a task, commit, push and create a new merge request.

Hints

1. Don’t bother creating an issue if you’re just creating an obvious change that doesn’t need context.

Gitlab code review conventions

Gitlab facilitates a lot of automation so that once effort from a colleague is requested, most basic checks have been performed. For example, most projects will provide CI jobs for:

• Linting (automated code style checking)
• Spellchecking
• Testing (running unit tests and/or end-to-end tests)

While you’re working on the above, it’d be best to keep your code in a branch or an MR that’s marked Draft. This signals the MR is not ready for review yet.

As the author of the branch/MR, you’re responsible to get the MR green-lit.

Once the CI pipeline is all green, and you’re happy with it, you can:

• assess your test coverage visualization. This works if the unit tests ran successfully and your project has coverage indication setup. Consider extending your test coverage if there are vertical red lines visible in your diff.
• wait for a reviewer to pick up the MR and provide you a code review
• if you’re in a hurry to get something merged, or you have someone specific in mind to review your code, assign that person as a reviewer to the MR.

Note

Everyone can partake in the review process. If you’re a junior, try to learn from it and ask questions when you don’t understand the structure or architecture, that may lead to better documentation in the code. Also, spotting typos or improved sentences are valid code review comments. You see, code review is not just for senior developers.

Reviewing back and forth

When a reviewer finished reviewing, either:

• comments are left to the author to work on or respond to. The MR may be reset to Draft state as well.
• the MR is merged right away because it was perfect.

Both the author of the MR and reviewer can resolve comments in an MR. Let’s leave the setting of resolved status to the reviewer only to keep the overview for the reviewer.

To signal the reviewer the MR is ready for another review:

1. Remove the Draft state (if it was in that state)
2. Request a re-review

Or, if you have a question for the reviewer use @username style notifications.

Note

Gitlab can send a lot of email notifications. One way of preventing this is, adding a sieve filter for your email moving all email “from gitlab.d-centralize.nl” and “draft in topic” to a special folder. Be aware of this.

Developer communication

Assume no other developer will see your MR, issue or comment in Gitlab. If you want to draw attention to it, trigger one of the actions that create a to-do item for another developer. The to-do list should be something that every developer monitors.

Merging

By default, the reviewer is allowed to merge the MR when accepted. In some project however (Appsemble), the reviewer is kindly asked to approve the MR and leave the merging to the author of the MR.

Self merging your code is generally not accepted. Within some projects where there are a lot of trivial bump MRs required, we leave the choice of self merging trivial MRS to the author.

Running Gitlab CI/CD job locally

A lightweight alternative to consider before running a full-blown docker based CI job.

Reuse through scripting

Instead of putting all shell scripting inside the .gitlab-ci.yml job definition, you can also just use it to execute .ci/some_script.sh.

Benefits of this approach:

• You can lint the script automatically.
• You can also locally call this script without the need of running in a Docker container (usually).

Some general advise:

• Stick with the most basic shell /bin/sh for scripts that just execute a bunch of commands.
• Stick with /bin/bash for scripts that need a little extra.
• Consider python if the script gets really big, complex or otherwise unreadable.

local CI job

Prerequisites:

1. Have gitlab-runner installed.
2. Have Docker installed.

To run a specific docker job:

gitlab-runner exec docker my-job-name

To add one or more environment variables:

gitlab-runner exec docker my-job-name --env YOUR_VARIABLE=value
gitlab-runner exec docker my-job-name --env YOUR_VARIABLE1=value --env YOUR_VARIABLE2=value ...

For more information: gitlab-runner exec docs

Issues

What can be said about issues is mostly not Gitlab specific and mentioned in Scrum.

Described here is useful knowledge specific to (our) Gitlab instance.

Labels

Labels can be used to categorize issues. But also to trigger behavior in dc scripts, the bot, and the recurring issues:

• gitlab/focus_on_urgency.py

This script fetches issues from Gitlab with the Priority: Urgent label assigned. If any issues are open, they get announced on Mattermost daily. For Appsemble it’s Prio::High and a daily announce on Discord.

• gitlab/unblocked_notifications.py

This script fetches issues from Gitlab with the Blocked label assigned. If all the issues in “Linked Items” changed status to “closed”, the Blocked label is removed along with a comment in the previously blocked issue.

When applying labels to your issues, try to select one or more of the “standardized” labels as shown in the image below. Those are acted upon by several scripts. When you feel the need to express more context, create project-specific labels on project level that make sense in the project context. These are only for humans, scripts will ignore those.

Bot directives

These labels can give the bot some hints in order to assign the right people to issues:

• Difficulty::easy: not much in depth programming knowledge is needed for this issue.
• FirstContribution: same as above.
• Difficulty::junior: some in depth programming knowledge is required for this issue.
• Skill:domain: some domain knowledge is needed for this issue (therefore, it might not be ideal for people not familiar with the project)
• Skill:fullstack: to finish the issue, work in frontend and backend is anticipated.
• Skill:dbmigration: to finish the issue, a database structure change and/or migration needs to be performed.
• Priority::Critical: drop everything, work only on this. Use when the majority of users are severely affected by this.
• Priority::Urgent: top priority to process this issue above all others. Use when several users are severely affected by this.
• Priority::High: high priority to process this issue above all others, except for the Urgent priority labeled issues.
• Priority::Normal: normal priority to process this issue. Needs to get done at some point in time.
• Priority::Low: low priority to process this issue. Only work on this when Urgent, High or not prioritized issues are processed already.
• TechDebt: Issues related to technical debt, including code that needs refactoring, outdated dependencies, or improvements to maintainability and performance. These are not immediate bugs but should be addressed to ensure long-term stability.
• Bug: Reports of unintended behavior, errors, or malfunctions in the software that need to be fixed. Bugs can include broken features, incorrect calculations, crashes, or unexpected performance issues.
• Feature: Requests or tasks related to adding new functionality or enhancing existing features in the software. These issues typically involve development work to introduce new capabilities or improve user experience.
• Client: Issues, requests, or tasks specifically related to a client or customer. This may include client-reported bugs, feature requests, integrations, or customization needs.

There are also two other labels that the recurring issues scripts use to automatically make issues:

• Type::cron-job: when you give this label to a issue the script will search for a cron statement. And based on that makes a issue.
• Bot::issue: This label indicates that the issue was made by the script.

Label Naming Conventions

To ensure consistency and clarity across our GitLab instance, please follow these naming conventions when applying labels:

1. General Structure:

   • Use capital letters for all labels. and also with double colons (::) separating the category and the label name (e.g., Priority::High). Or only the first word (e.g., Bot::issue)
     • While we do use scoped labels (::), it’s a feature from a higher tier in Gitlab we don’t pay for. So they don’t work as expected. However, additional scripting will compensate for that. For example when a issue has both the High and Low priority it may remove one of those labels from the issue.
   • Use descriptive, short names for labels that clearly indicate their purpose.
   • No spaces between words in labels; use double colons (::) instead (e.g., Difficulty::Easy, Skill::Domain).
   • All “standardized” labels need to be made in the dc Gitlab group and not any of it’s sub-groups or projects.

2. Label Categories:

   • Priority Labels: Use labels like Priority::High, Priority::Low, Priority::Urgent, and Priority::Critical to denote issue priority.
   • Difficulty Labels: Use labels such as Difficulty::Easy, Difficulty::Junior, or Difficulty::Senior to describe the complexity of the issue.
   • Skillset Labels: Use Skill::Fullstack, Skill::Backend, Skill::Frontend, etc., to indicate the skillset required.
   • Status Labels: Use Status::Todo, Status::InProgress, Status::Blocked, Status::Closed to denote the issue status.
   • Type Labels: Use Type::Bug, Type::Feature, Type::Documentation, etc., to categorize the type of work involved in the issue.

3. Do not create custom labels: Stick to the official labels provided in the GitLab dropdown list. Only create new labels on the project level if your project needs this and stick to the conventions.

Recurring Issues

Overview

This guide explains how to set up and manage automated recurring issues in GitLab. The script checks for issues labeled Type::cron-job, extracts scheduling information, and creates new issues based on the specified schedule. It also closes outdated issues to keep the issue tracker clean. By making a issue with the Type::cron-job this issue will keep making a issue, until the issue is manually closed/deleted by a user.

Example

For help creating cron expressions, visit: Crontab Guru. If an issue includes the schedule 0 0 * * 0, meaning it should create a new issue every sunday at midnight, the script will:

1. Create a new issue every sunday at midnight.
2. Close the previous issue once the new one is created.

Creating an Automated Issue

To schedule a recurring issue, follow these steps:

1. Go to the Issues Page

   • Navigate to the “Issues” section of your GitLab project.

2. Create a New Issue

   • Click ‘New Issue’.

3. Fill in the Issue Details

   • Title: Use a clear title like Automatic issue for the weekly meeting (template).

     • The brackets() in the title are optional. But they can be handy so everyone knows that noting important is in the issue.
     • Everything you put between brackets in the title will be removed in the task that is created and be replaced with: (created from Cron template issue: (link to the template issue))

   • Description: Add a cron schedule and description. It can be useful to add a description to the issue but it is optional. The cron label is required! If you think the issue needs more info add a description to make it more clear. The cron: part can be anywhere in the description. It just needs to be on it’s own line. Example:

     Some useful information for the issue.
     cron: 0 0 * * 0
     This is the weekly issue for the weekly meeting.

   • Make sure you add the cron statement directly after the cron: part. Otherwise the script will not find the cron statement.

   • Label: Assign the label Type::cron-job.

4. Submit the Issue

   • Click ‘Submit issue’.

The script will now detect this issue and process it according to the schedule. The next time the script runs it will create the issue. Using above example the script will make the issue with the title: “Automatic issue for the weekly meeting (link to the template issue).” description: “This is the weekly issue for the weekly meeting. 0 0 * * 0” And lastly it will have the label Type::BotLabel.

Support desk

Email address connection

• Activate the service desk from the Gitlab project settings (example).
• Setup a support@ email inbox as described in the e-mail server instructions and make itforward to the email address generated by Gitlab.
• Setup the “Configure a custom email address” section .

Automation

Support projects can be configured through md files like the one from its-support so all incoming support issues obtain urgent priority and several team members can be notified. Make sure that after the Default.md is merged in main, it’s configured as Template to append to all Service Desk issues from the Gitlab project settings. General Settings > Service Desk.

Notifications

Announce any new support issues on Mattermost. Usually in the #support channel. For this, setup an integration example with Mattermost.