GitLab

Journaux liées à cette note :

Voici-ci dessous, une partie de la liste de labels d'Issues que l'équipe tech de Spacefill utlisait sous GitLab. Cette liste de labels est le fruit d'un travail itératif d'environ 15 personnes, sur une période de 4 ans.

Voici comment cette liste a été élaborée :

Au départ, quelques labels ont été créés de manière organique par 3 développeurs et un product manager.
Après 3 mois d'usage, une page de documentation nommée "GitLab Spacefill labels" a été ajoutée au handbook de l'équipe.
Ensuite, au fur et à mesure des nouvelles problématiques rencontrées et de l'évolution des workflows, ce fichier de documentation a été amendé plus de 70 fois en 3 ans, par 11 contributeurs différents.
Ce document était modifié suivant le même processus que le reste du handbook et le code :
- Une personne commençait par créer une issue pour décrire une problématique
- Ensuite, cette même personne ou une autre faisait une proposition d'évolution du processus par la rédaction d'une Merge Request qui modifiait cette page de documentation
- Puis cette Merge Request entrait dans une phase de review par l'équipe, était corrigée, amendée...
- Et finalement, quand cette Merge Request était approuvée par toute l'équipe, elle était mergée et ensuite respectée par tous

J'ai conservé cette liste afin de pouvoir l'utiliser comme source d'inspiration ou de fondation pour mes prochains projets en équipe.

Pour ceux qui souhaitent s'en inspirer, je recommande de ne pas adopter cette liste intégralement d'emblée. Privilégiez plutôt une sélection ciblée des labels qui correspondent à vos processus actuels, puis incorporez progressivement de nouveaux labels selon l'évolution de vos besoins.

Mon expérience m'a démontré que la mise en place de processus dans une organisation humaine fonctionne mieux par petites étapes successives. Cette approche incrémentale s'avère bien plus efficace que de tenter d'imposer en bloc un processus complet qui risquerait d'être inadapté à votre contexte spécifique.

Voici cette liste.

Labels pour indiquer les types d'issue

Une issue doit avoir dans tous les cas un type et un seul type.

Couleur : FOAD4E

type::user-story : une issue qui apporte une fonctionnalité à l'application
type::improve : une issue qui apporte une amélioration mineure à une fonctionnalité existante, qui est plus simple de ne pas exprimer sous forme d'une user story, et qui bien sûr n'est pas un bug.
type::documentation-and-process : problème ou amélioration d'un process ou d'une documentation interne (les deux sujets documentation et processus sont liés parce que les processus sont documentés). La documentation du logiciel à destination des usagers de l'application n'entre pas dans cette catégorie, elles sont du type user-story, improve ou bug.
type::enabler : un changement qui n'apporte pas directement de valeur aux utilisateurs de l'application. Ce type est utilisé pour des issues dont le but est d'améliorer l'expérience des développeurs (voir définitions : SAFe Enablers,Les enablers en agile)
type::technical-debt : definition, label à utiliser, par exemple pour des issues dont le bug est d'upgrader une librairie, d'améliorer une implémentation, ou une proposition de refactoring… Ce label ne doit pas être utilisé pour des issues "produit".
type::support-ops : pour les tâches de support qui ne nécessitent généralement pas de merge request, par exemple : des migrations de données, des corrections de données, des extractions de données…
type::spike : voir la definition
type::meta : pour des issues de type "meta", par exemple, des issues dont le but est de créer d'autres issues, de faire de l'affinage d'issues, ou organiser des rituels…
type::meta-spec-writing : pour des issues dont l'objectif est de créer des issues ou des Epic, dont le but est de rédiger des spécifications techniques, ce sont des sortes d'issues de type "meta", mais plus spécifiques.

Couleur : D9534F

type::bug : pour des issues qui décrivent des dysfonctionnements de l'application
type::bug-job-CI : pour des issues qui décrivent des bugs de CI

Labels pour indiquer la priorité des issues

Couleur : FF0000

priority::critical : une issue qui doit obligatoirement être traitée tout de suite par un développeur
priority::24h : une issue qui doit être traitée d'ici 24h
priority::7days : une issue qui doit être traitée d'ici à 1 semaine

Labels de workflow

Une issue doit avoir un et seulement un label de type workflow, un et un seul label de type product-review.

Couleur : 0033CC

Draft
- workflow::need-product-specs : l'issue doit être spécifiée par un membre de l'équipe produit
- workflow::need-design : l'issue a besoin de wireframe, design, …
- workflow::need-tech-specs : l'issue doit être affiner par un membre de l'équipe tech
To do
- workflow::ready-for-development : l'issue est prête à être implémentée
- workflow::to-be-continued : l'issue a été commencée, mais mise en pause parce que le développeur est assigné sur une autre issue.
- workflow::doing : un développeur est en train de travailler sur cette issue
- workflow::ready-for-first-review : l'issue est prête à être review par un développeur
- workflow::ready-for-maintainer-review : l'issue est prête à être review par un maintainers
- workflow::blocked : l'issue est bloquée Par exemple :
  - l'issue est commencée, elle peut avoir une merge request de prête, mais le développeur ne peut pas la terminer, car elle dépend d'une autre Merge Request en cours d'élaboration ;
  - l'auteur de l'issue attend une réponse d'une personne externe de l'équipe produit ou tech, par exemple un client.
- workflow::ready-for-merge : l'issue a été review et est prête à être mergé
- need-cto : l'issue est bloquée parce qu'elle est en attente d'une validation par le CTO
Product review
- product-review::needed : indique que l'issue doit être review par un membre de l'équipe produit
- product-review::not-needed : indique que l'issue n'a pas besoin d'être review par l'équipe produit
- product-review::pending : issue en attente de review par un membre de l'équipe produit
- product-review::feedback : une demande de correction a été émise par un membre de l'équipe produit
- product-review::approved : la Merge Request a été review et validée par un membre de l'équipe produit avec plus aucune demande de correction

Labels d'intégration dans des boards

Couleur : 428BCA

board-product-refinement : pour intégrer des issues dans un Kanban board qui contient une liste d'issues que l'équipe produit doit affiner
board-tech-refinement : pour intégrer des issues dans un Kanban board qui contient une liste d'issues que l'équipe tech doit affiner
board-support : pour intégrer des issues dans un Kanban board qui contient une liste d'issues de support qui traitent des demandes externes à l'équipe tech ou produit.
board-cto : utilisé par le CTO pour suivre des issues "cross team"

Labels divers

Couleur : 7F8C8D

first-contribution : pour identifier des issues en théorie facilement réalisables par un nouveau développeur en phase d'onboarding.
sprint-planning : pour les issues de type meta, dont l'objectif est d'organiser le rituel Sprint Planning.
sprint-retrospective : pour les issues de type meta, dont l'objectif est d'organiser le rituel Sprint Retrospective.
sprint-retro-follow-up : pour identifier les sujets qui ont été remontés lors d'une session de Sprint Retrospective.
triage : pour identifier les issues qui doivent être triées, c'est-à-dire, décider si l'issue doit être abandonnée pour être placée dans un backlog.
need-to-be-planned : pour identifier des issues validées, mais qui doivent être planifiées, c'est-à-dire, être ajoutées dans un sprint
danger : pour identifier des issues qui doivent être traitées avec prudence, qui par exemple risquent de détruire des données.
tech-refinement : pour identifier une issue qui doit être affiner par l'équipe tech, mais qui n'a pas encore été ajoutée dans le board-tech-refinement.
tech-refinement-removed : pour identifier des issues qui étaient dans un board-tech-refinement mais qui n'ont pas été affiné par manque de temps et donc repoussées à une future session.
security : pour identifier des issues en lien avec la sécurité informatique, par exemple, un risque de fuite de données, de perte de données, d'intrusion…
version-outdated : pour identifier les issues dont l'objectif est la mise à jour de librairies ou de services.

Label de compétences nécessaires

Liste de labels peu utilisés, ils permettaient d'identifier les compétences techniques nécessaires pour pouvoir traiter l'issue.

Couleur : 5843AD

skills:ansible
skills:terraform
skills:nodejs
skills:postgraphile
skills:html/css
skills:docker
skills:gitlab-ci
skills:docker
skills:dev-ops
skills:postgres
skills:postgres-rls
skills:postgres-rbac
skills:postgresql-plsql
skills:postgresql-policy
skills:reactjs
skills:shellscript
skills:sql

Depuis un an, j'ai pris conscience d'une difficulté inhérente aux organisations qui suivent le paradigme Multirepos, difficulté dont je ne m'étais pas rendu compte auparavant : décider où publier ses issues !

J'ai observé que dès qu'une organisation commence à utiliser plusieurs repositories, la question de l'endroit où créer de nouvelles issues se pose. Par exemple :

Où poster une issue d'amélioration qui nécessite des changements dans le repository A et B ?
Où créer une issue d'une proposition d'un process qui ne concerne pas spécifiquement le code source d'un projet hébergé dans un repository ?
Où créer une issue dont le but est de créer un nouveau service ?

Quand une organisation suit le paradigme Monorepo avec issues colocalisées et utilise, comme je l'explique dans la note "Nom et arborescence de Monorepo" un nom non spécifique, alors la question de l'endroit où publier ses issues ne se pose pas ! Il suffit de publier l'issue dans le Monorepo (par exemple sur GitHub, GitLab ou Forgejo).

Le gestionnaire d'issue du Monorepo est un point de schelling, c'est-à-dire un endroit où tous les développeurs convergent naturellement en l'absence de communication explicite pour trouver et créer des issues.

Ce paradigme évite des débats à propos de l'endroit où publier les issues.

Je suis un adepe du paradigme Monorepo, de la documentation colocalisée et des issues colocalisées.

Je conseille de nommer le repository avec le nom de l'organisation.

Par exemple, si mon organisation se nomme « Dummy Tech » et si elle utilise GitLab, alors je conseille d'utiliser le slug dummy-tech, ce qui donne gitlab.com/dummy-tech/dummy-tech/ et « Dummy Tech Monorepo » comme titre de repository.

La neutralité de ce nom facilite les décisions concernant ce qui peut ou non être inclus dans le repository, sans être limité par un nom trop restrictif. Il est flexible face à l'évolution du projet. Il permet d'éviter bien des débats à propos du nommage.

En 2018, sur GitHub, j'ai découvert un exemple de monorepo d'une organisation. Cet exemple m'a servi de base et je l'ai fait évoluer quand je travaillais chez Spacefill.

Voici un exemple d'arborescence de monorepo que j'aime utiliser :

dummy-tech
├── deployments
│   ├── prod
│   └── sandbox
├── ci
├── docs
├── playgrounds
│   ├── playground_a
│   └── playground_b
├── services
│   ├── service_a
│   ├── service_b
│   └── service_c
└── tools
    ├── tool_a
    ├── tool_b
    └── tool_c

En 2016, Philippe Lafoucrière m'a appris que contrairement aux règles de typographie française, en typographie anglaise, il ne faut pas placer d'espace avant le caractère deux points :.
Je pense d'ailleurs que cette différence est peu connue par les Français et inversement.

Une des conséquences malheureuses de cette différence est la présence généralisée d'une popup de suggestion automatique d'émojis après la séquence <espace>: dans les éditeurs de texte Markdown. Cette fonctionnalité est activée par défaut, sans option pour la désactiver, par exemple, dans GitHub, GitLab ou Discourse.

Exemple :

En 2022, j'ai implémenté et publié un User Styles pour Firefox (maintenant LibreWolf) basé sur Stylus pour désactiver cette autosuggestion automatique d'émojis sur GitHub, GitLab.

Je viens d'ajouter une règle pour Discourse.

Voici ces règles exécutées par Stylus (le fichier) :

@-moz-document regexp("http.*gitlab.*") {
    .atwho-container #at-view-58 {
        display: none !important;
    }
}

@-moz-document domain("github.com") {
    [class^="AutocompleteSuggestions"] {
        display: none !important;
        visibility: hidden !important;
    }
}

@-moz-document regexp(".*discourse.*"), regexp(".*discussion.*") {
    .autocomplete.ac-emoji {
        display: none !important;
    }
}

Comment l'installer ?

Installer l'extension Firefox : https://add0n.com/stylus.html
Et ensuite, cliquer sur le lien suivant pour installer mon fichier User Styles : https://github.com/stephane-klein/dotfiles/raw/refs/heads/main/userstyles/disable-gitlab-github-discourse-emoji-picker.user.css

Je vais essayer de rassembler mes User Styles dans ce dossier : https://github.com/stephane-klein/dotfiles/tree/main/userstyles.

Alexandre m'a fait remarquer que GitLab a activé par défaut une extension Markdown de génération automatique de TOC :

A table of contents is an unordered list that links to subheadings in the document. You can add a table of contents to issues, merge requests, and epics, but you can’t add one to notes or comments.

Add one of these tags on their own line to the description field of any of the supported content types:
[[_TOC_]]
or
[TOC]
Markdown files.

Wiki pages.

Issues.

Merge requests.

Epics.

source

Je trouve cela excellent que cette extension Markdown soit supportée un peu partout, en particulier les issues, Merge Request… 👍️.

Cette fonctionnalité a été ajoutée en mars 2020 🫢 ! Comment j'ai pu passer à côté ?

GitHub permet d'afficher un TOC au niveau des README, mais je viens de vérifier, GitHub ne semble pas supporter cette extension TOC Markdown au niveau des issues… Pull Request…

La fonctionnalité "Activité" de GitLab me manque dans GitHub.

Voici trois exemples concrets de fonctionnement de cette fonctionnalité, dans trois contextes différents.

Le premier, dans le projet GNOME Shell :

Le second, dans le groupe Wayland : https://gitlab.freedesktop.org/groups/wayland/-/activity

Et le troisième, pour l'utilisateur Lucas Stach: https://gitlab.freedesktop.org/users/lynxeye/activity

Je trouve cette fonctionnalité très utile quand on travaille sur un projet. Elle permet d'avoir une vue d'ensemble de ce qui s'est passé sur un projet sur une période. Elle vient en complément de l'historique Git qui est limité aux changements effectués sur le code source.

Dans certaines situations, je sais qu'un collègue travaille sur un sujet qui me concerne et la fonctionnalité "Activité" me permet de mieux comprendre où il en est, de suivre facilement ce qu'il fait.

Cette fonctionnalité "Activité" permet de pratiquer la stigmergie.

J'utilise aussi cette fonctionnalité lors de la rédaction d'un rapport d'activité ou d'un message de Daily Scrum. Elle m'aide à retrouver précisément ce que j'ai fait dernièrement.

Je trouve la page "Contribution activity" d'un user GitHub limité, par exemple, elle ne contient pas l'historique des commentaires.

Même chose au niveau d'un projet, dans la page "Pulse", par exemple : https://github.com/sveltejs/kit/pulse.

Je viens de regarder du côté de Codeberg / Forgejo : <https://codeberg.org/forgejo/forgejo/activity. Même constat que pour GitHub, les informations sont très réduites.

Je viens de réfléchir à l'usage des termes "development environment" et "development kit".

Je pense que le dépôt gitlab-development-kit est un "development kit" qui permet d'installer et configurer un "development environment" pour travailler sur le projet GitLab.

#JaiDécouvert Sourcebot (from) :

Sourcebot is an open-source code search tool that allows you to quickly search across many large codebases.

C'est une alternative à Sourcegraph.

Je suis ravi de voir qu'il existe de plus en plus d'alternatives communautaires à GitHub ou GitLab, comme Forgejo, Weblate, Woodpecker CI et maintenant Sourcebot.

Lorsque vous collaborez avec moi et partagez du code source ou des extraits de terminal dans un logiciel compatible avec le format Markdown, tel que GitHub, GitLab, Mattermost, Zulip, etc., je vous encourage à entourer vos extraits avec des balises ```. Par exemple :

De même, pour les citations de texte en prose, utilisez les caractères > au début de chaque ligne, comme illustré ci-dessous :

> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse justo neque, facilisis ut commodo in, auctor at tellus. Morbi non mattis risus. In vehicula risus felis, ac ullamcorper magna consequat et.
> Sed finibus, lorem a rutrum pulvinar, magna urna rutrum tortor, eget faucibus dolor enim sit amet lacus. Nulla pulvinar ligula eu leo rhoncus faucibus.

Ce qui produira :

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse justo neque, facilisis ut commodo in, auctor at tellus. Morbi non mattis risus. In vehicula risus felis, ac ullamcorper magna consequat et. Sed finibus, lorem a rutrum pulvinar, magna urna rutrum tortor, eget faucibus dolor enim sit amet lacus. Nulla pulvinar ligula eu leo rhoncus faucibus.

Ces deux recommandations permettent d'améliorer le confort de lecture de vos messages.

Voir aussi je préfère recevoir les extraits de vos textes au format texte plutôt que sous forme de captures d'écran.

Je préfère ne pas utiliser le terme « ticket » pour traduire « issue » en anglais.
Il m'arrive cependant d'employer « ticket » uniquement pour désigner les demandes de support ou les bugs.

Les définitions proposées par le Wiktionary et Wikipedia semblent corroborer cette distinction :

« Billet comportant un numéro d’ordre de passage dans une file d’attente. »

-- définition wiktionary.

« Une demande d'assistance, désignées ainsi dans le métier de l'assistance sous le nom de ticket. »

-- wikipedia

Le terme anglais « issue » a une portée bien plus large que celle de « ticket ». Il peut désigner :

ChatGPT me dit :

En français, le terme "issue" peut être traduit de différentes manières en fonction du contexte. Voici quelques traductions courantes :

Problème : C'est la traduction la plus directe et souvent utilisée. Elle est appropriée si l'"issue" en question concerne un bug ou un défaut à corriger.

Ticket : Ce terme est également couramment utilisé dans le contexte du suivi des tâches ou des bugs. Il est un peu plus neutre et peut désigner aussi bien un problème qu'une demande de fonctionnalité.

Tâche : Si l'"issue" représente quelque chose à faire (comme une nouvelle fonctionnalité à développer), "tâche" peut être une bonne traduction.

Demande : Ce terme peut être utilisé si l'"issue" est une requête ou une demande de changement.

En fonction du contexte précis, tu peux choisir le mot qui semble le plus approprié. Par exemple :

Pour un bug : Problème ou Bug.

Pour une nouvelle fonctionnalité : Tâche ou Demande.

De manière générale, dans le cadre d'un système de gestion de projet : Ticket.

Le terme "issue" est parfois laissé tel quel en français dans certains contextes techniques, surtout dans des équipes habituées aux outils comme GitLab ou GitHub.