Gitlab

Introduction

Nous nous efforçons d'utiliser le plus possible notre instance GitLab pour les différents aspects de notre administration : sauvegarde et versionnage des configurations des services, remontée et traçabilité des problèmes et des améliorations, archivage des comptes-rendus des réunions, écriture et publication de la documentation.

GitLab constitue ainsi le centre névralgique de notre activité, c'est pourquoi nous en documentons ici précisément les protocoles d'utilisation. Pour plus de détails sur le logiciel en tant que tel, veuillez vous référer à la documentation officielle, en gardant en tête que nous utilisons la version GitLab Community Edition.

Groupes et projets

Notre association est partagée entre plusieurs activités principales qui doivent être correctement reflétées à travers l'arborescence de notre instance GitLab.

Arborescence

info

Pour un maximum de transparence, les groupes et les projets sont publics par défaut, mais pour des raisons de sécurité, le contenu des /etc n'est pas public. Si des besoins de sécurité supplémentaires sont avérés, il est possible de réduire la visibilité de l'ensemble d'un projet aux membres de la FELINN seul·es, aux administrateurices ou aux membres du conseil collégial.

Groupe « FELINN core »

Le groupe FELINN core est consacré aux [services en production et pré-production](cf docs services), à la gestion de l'infrastructure et à notre organisation associative.

Pour chaque service, il existe un projet dont le nom est l'URL du service :

https://cloud.felinn.org --> https://git.felinn.org/FELINN/cloud.felinn.org

Chaque projet de service contient le /etc du container ou de la machine virtuelle qui contient le logiciel du service, grâce à etckeeper.

attention

Si des fichiers ou dossiers de configuration du logiciel ne sont pas initialement dans /etc, on y crée un lien symbolique (à ajouter explicitement avec git add) afin de centraliser la configuration. Voir le voir le versionnage des services.

info

Le sous-groupe tools regroupe les scripts automatisant des tâches récurrentes d'administration.

Groupe « FELINN labs »

Le groupe FELINN labs est consacré aux services expérimentaux et aux recherches de la FELINN. Les services ayant vocation à rejoindre l'offre de la FELINN, même en cours de test, doivent être placés dans le groupe FELINN core.

Groupe « Friends of FELINN » (FoF)

Le groupe FoF est dédié aux projets de nos partenaires et/ou aux projets que nous développons pour elleux. Nous utilisons un sous-groupe par partenaire si plusieurs projets sont envisagés, sinon un projet directement dédié au partenaire.

Gestion des groupes, sous-groupes et projets

En l'état actuel, nous n'envisageons pas la nécessité de créer un nouveau groupe, ni de modifier ou supprimer l'un des trois groupes existants (FELINN core, FELINN labs, FoF). Seule une délibération en conseil collégial pourrait aboutir à un tel événement.

Dans les sections qui suivent, « unité » signifiera indistinctement un sous-groupe ou un projet.

Création

protocole

Pour créer un nouveau sous-groupe ou projet, il faut suivre et respecter les étapes suivantes :

1. Avoir un objet unique et précis qui correspond à un besoin très concret. Il faut donc vérifier qu'il ne fasse pas doublon ou qu'il ne puisse pas être intégré à une autre unité existante, ou inversement.
2. Ouvrir une issue titrée « [unité : création] nom de l'unité concernée », et dont la description détaille le besoin et l'objectif.
3. L'issue doit être approuvée ai niveau CC-I.
4. Si approuvée (discussions et réévaluation possible en commentaire), l'issue doit donner lieu à la création de l'unité et à la désignation des membres qui seront responsables de son administration, ainsi qu'à la mise en place des permissions.
5. S'il s'agit d'un service ou d'un ensemble de services, identifier son état, expérimental ou non. Dans le premier cas, l'unité doit être placée dans FELINN labs ; dans le second, elle doit être placée dans FELINN core.
6. Pour un maximum de lisibilité et d'uniformité, il est fortement recommandé d'ajouter une icône (colorée en #743AE7) pour chaque nouvelle unité.

Mise à jour

Les membres des sous-groupes et projets doivent suivre le plus régulièrement possible en assurer le suivi, notamment au moyen des issues. Celles-ci doivent être régulièrement passées en revue et mises à jour afin d'éviter les issues zombies.

Dans le cas où un projet ou un sous-groupe devrait être déplacé, il faut suivre et respecter les étapes suivantes :

protocole

1. Ouvrir une issue avec le titre « [unité : transfert] nom de l'unité concernée » avec en description les motivations explicites et argumentées.
2. Le déplacement doit être validé au niveau CC-I.
3. Si la décision est positive et que l'unité comporte des utilisateurices, il faut en informer toutes les personnes concernées (via les @ ou par mail), en précisant le délai avant transfert (au moins une semaine pour un service) ainsi que les modalités de discussion ou objection, qui doivent toujours être possibles.
4. Si c'est un projet, l'archiver dans la mesure du possible plutôt que de le supprimer. Le supprimer si c'est un sous-groupe.
5. ⚠️ Ne pas fermer l'issue du transfert tant que nous ne sommes pas sûres que tous les potentiels git remote url n'ont pas été mis à jour

Suppression

Pour supprimer un sous-groupe ou un projet non-vide il faut suivre et respecter les étapes suivantes :

protocole

1. Ouvrir une issue avec le titre « [unité : suppression] nom de l'unité concernée » avec en description les motivations explicites et argumentés. Si c'est un sous-groupe, il faut si besoin proposer d'en transférer les projets avant la suppression, et ce dans la même issue.
2. La suppression doit être validé au niveau CC-I.
3. Si la décision est positive et que le projet/sous-groupe comporte des utilisateurices, il faut en informer toutes les personnes concernées (via les @ ou par mail), en précisant le délai avant transfert (au moins une semaine pour un service) ainsi que les modalités de discussion ou objection, qui doivent toujours être possibles.
4. Si l'unité est un projet, une discussion doit être menée sur l'opportunité de son archivage, plutôt que de sa suppression pure et simple.

Rôles

GitLab utilise 5 rôles pour gérer les permissions (documentation officielle):

• Guest (invité·e)
• Reporter (reporteureuse)
• Developer (développeureuse)
• Maintainer (mainteneureuse)
• Owner (propriétaire)

Par défaut, pour les groupes et projets de la FELINN, les rôles sont associés aux différents statuts de l'association :

• les membres du conseil collégial sont propriétaires,
• les administrateurices sont développeureuses sur les projets qu'iels veulent intégrer,
• les membres sont reporteureuses par défaut, pour leur permettre de s'impliquer sans risque d'introduire des bugs,
• les utilisateurices partenaires sont invité·es sur les projets qui les concernent (dans le groupe FoF)

attention

Pour changer de rôle sur GitLab, il faut donc nécessairement [changer de rôle au sein de l'association](section association changement de statuts).

Issues

Une issue est un ticket qui permet le référencement, la traçabilité et l'archivage d'un événement lié au projet auquel il appartient.

Ouverture

• S'assurer via la fonction de recherche de GitLab qu'une issue similaire et non résolue n'existe pas déjà.
• Vérifier que l'issue à créer corresponde à un type d'événement valable, c'est-à-dire :

• un dysfonctionnement dont les contours sont définissables précisément (bug)
• une proposition d'amélioration
• un sujet d'organisation

protocole

1. Vérifier que l'issue concerne directement le projet dans lequel on l'ouvre. Par exemple, une issue à propos d'un bug du cloud doit être ouverte dans le projet cloud.felinn.org.
2. Écrire un titre court (environ 10 mots maximum), explicite, précis et non ambiguë. Par exemple, « les salons de la FELINN sur Matrix n'envoient plus les notification » est un bon titre tandis que « je ne vois pas les notifications » n'est pas un titre assez précis.
3. Utiliser un template (ou modèle) proposé dans la liste déroulante en dessous du titre, qui doit être remplis la plus complètement possible.
4. Classer au mieux l'issue grâce par la classification, il est préférable d'assigner un (et un seul) label par catégorie.
5. Assigner l'issue au ou à la membre de la FELINN qu'on pense être le·a plus compétent·e sur le sujet. Si besoin, communiquer avec les autres membres sur le canal approprié (messagerie instantanée) pour déterminer la personne en question.
6. Assigner un milestone (cf milestones), voire une due date (échéance), à condition d'en avoir l'autorisation et de savoir exactement ce que l'on fait.

Fermeture

protocole

1. Un bug est fermé lorsqu'il a été résolu et que sa résolution a été documentée dans l'issue ainsi que dans le wiki du projet correspondant (dans les cas où une intervention côté système s'est avérée nécessaire).
2. Une amélioration est fermée lorsque celle-ci a soit :
3. été implémentée et documentée dans l'issue ET dans le wiki correspondant
4. été abandonnée par la personne qui a proposé l'amélioration. Dans ce cas, un label 'abandon' doit d'abord être appliqué temporairement, puis une délibération dans l'issue doit décider de sa fermeture ou non.
5. Un sujet d'organisation est clos lorsque les points qui y sont soulevés ont été traités et le cas échéant traduits en issues, ou lorsqu'une [décision](Cf asso/décisions) a été prise quant au sujet de la discussion.

Labels

Les labels sont des catégories nommées, colorées et légendées de manière à trier, rechercher et donc prendre en charge plus rapidement et facilement les issues.

Classification

• Les labels du groupe FELINN core & FELINN labs sont listés ici.
• Les labels du groupe FoF sont moins nombreux, afin de faciliter leur prise en main par les utilisateurices invité·es, ils sont listés ici

Pour chaque classe, les labels ont vocation à être exclusifs entre eux (e.g. on ne peut pas classer une issue à la fois comme P1 et P2).

Création

protocole

1. Déterminer un label unique et précis qui correspond à un besoin concret pour un groupe.
2. Vérifier qu'il ne fasse pas doublon avec un label existant.
3. Ouvrir une issue titrée « [label] objet du label », et dont la description détaille le besoin et l'objectif.
4. L'issue doit être approuvée au niveau CC-I.
5. Si approuvée (discussion et réévaluation possible en commentaire), l'issue doit donner lieu à la création du label correspondant au niveau du groupe.

Suppression

protocole

1. Déterminer que le label est inutilisé ou utilisé en doublon avec un autre.
2. Ouvrir une issue titrée « [label : suppression] nom du label », et dont la description détaille le besoin et l'objectif.
3. L'issue doit être approuvée au niveau CC-I.
4. Si approuvée (discussions possible en commentaire), l'issue doit donner lieu à la suppression du label correspondant au niveau du groupe.

Milestones

Les milestones permettent de jalonner dans le temps l'avancée du développement des projets internes et de la FELINN. On utilise pour ce faire un système de versionnage sémantique: MAJEUR.MINEUR.PATCH.

La création d'un milestone fait suite à un besoin exprimé dans une ou plusieurs issues qui, en fonction de leur urgence et de leurs nature, ne sont pas appropriées aux feuilles de route (roadmap) existantes. Une discussion préalable suivie d'une décision du conseil [préciser] est nécessaire à la création d'un nouveau milestone.

En cas de contrainte précise dans le temps, une échéance (due date) peut être ajoutée au milestone.

Les milestones de la FELINN en elle-même n'ont pas d'échéance, car ce n'est pas un projet, i.e., un milestone est terminée lorsque l'ensemble des issues afférentes y sont fermées.

astuce

Une échéance lointaine peut toutefois être ajoutée uniquement pour que les issues qui appartiennent au milestone apparaissent en premier.

Commits

Les commits permettent une traçabilité fine et un retour dans le passé, c'est pourquoi ils doivent être explicites et clairs. Il est néanmoins encouragé de faire des blagues (parce qu'on aime bien les blagues).

astuce

Si possible, les commits doivent être signés avec la clé PGP visible dans le profil de l'administrateurice ce qui permet de bien authentifier toutes les modifications du code et des fichiers de config.

tags

Les tags permettent de mettre visuellement en valeur certains commits. Les tags sont utilisés pour chaque sortie de version (release). Une nouvelle version est atteinte quand toutes les issues d'un projet attribuées à un milestone sont résolues. Le nom du tag est égal au nom du milestone qui correspond à la version ciblée. Les versions sont gérées selon un versionnage sémantique : MAJEUR.MINEUR.PATCH.

attention

Un changement de version majeure correspond à une rétro-incompatibilité logicielle.