Labels

This document outlines best practices for utilizing GitLab labels effectively across our projects.

Why Use Labels

Labels serve as a powerful organizational tool, enabling us to categorize and track issues efficiently. By using labels, we can:

  • Prioritize tasks effectively.
  • Gain insights into project progress and status.
  • Facilitate collaboration among team members.

Predefined Labels

At the EBRAINS RI level, we have predefined a set of high-level labels covering various topics, ticket states, and statuses. When opening a new issue, please review and utilize these predefined labels whenever possible.

Project Scoped Labels

Project scoped labels work in parallel with the high-level labels, but the difference is that these are not trackable from the TC team and may not be visualized at higher levels on GitLab boards. They are being used at the project level only.

Ticket Hierarchy

In our workflow, we use “high-level” tickets to represent epics or features. Tasks and related items are managed using the “child items” or “linked items” GitLab features. It’s important to understand that labels are assigned only at the “high level,” i.e., at the epic or feature description level, and not at the ticket child level.

High-Level Ticket

  • Title: Implement New Feature X
  • Description: This ticket represents the implementation of Feature X, which involves adding new functionality to our application.
  • Labels: Feature, Enhancement -> these are predefined labels from the TC list

Child Items

  1. Subtask 1:

    • Description: Research existing solutions for Feature X.
    • Assignee: John Doe
    • Labels: Research -> this one can either a predefined one (not the same with parent’s) or “scoped” or left empty

  2. Subtask 2:

    • Description: Design the architecture for Feature X.
    • Assignee: Jane Smith
    • Labels: Design -> this one can either a predefined one (not the same with parent’s) or a “scoped” or left empty

  3. Subtask 3:

    • Description: Implement frontend components for Feature X.
    • Assignee: Alice Johnson
    • Labels: Frontend -> this one can either a predefined one (not the same with parent’s) or a “scoped” or left empty

  4. Subtask 4:

    • Description: Implement backend logic for Feature X.
    • Assignee: Bob Brown
    • Labels: Backend -> this one can either a predefined one (not the same with parent’s) or a “scoped” or left empty

Important Note on Ticket Hierarchy

In this example, the high-level ticket “Implement New Feature X” serves as an epic or feature-level item, representing the overarching goal of implementing Feature X. This high-level ticket is labeled with relevant labels such as Feature, Enhancement to provide context and track its status.

The child items, represented by subtasks 1 through 4, break down the implementation process into smaller, manageable tasks. Each subtask is assigned to a specific team member and labeled accordingly to indicate its nature and assignment status (Research, Design, Frontend, Backend). Child items can hold predefined high-level labels or project scoped labels but those are not exclusively used in the main tracking board (ADD LINK)

By utilizing this ticket hierarchy along with labels and child items, teams can effectively track the progress of feature implementation, allocate tasks to team members, and ensure clear communication and collaboration throughout the development process.

How to Create Labels

If you find it necessary to create new labels, either at the project level or under special circumstances at the group level, please adhere to the following generic GitLab labeling guidelines to ensure consistency and effectiveness:

Use Descriptive Names

Choose label names that clearly describe the purpose or category of the label.

Color Coding

Use color coding wisely to make labels easily distinguishable at a glance. Follow the color scheme provided in the predefined labels if applicable.

Prefixes for Clarity

Consider using prefixes (e.g., type:, status:, priority:) to group related labels and facilitate filtering.

Documentation

Document the purpose and usage of each label in your project’s README or contributing guidelines to ensure all team members understand how to use them effectively.

For a comprehensive guide on creating and managing labels in GitLab, including best practices and tips for usage, refer to the GitLab Labeling Guidelines

Edit this page on GitLab ↗