Comprendre la hiérarchie des labels à deux niveaux

Ce que vous allez comprendre

  • Analyser pourquoi gitrust utilise deux types de labels indépendants plutôt qu'un seul système plat.
  • Évaluer l'impact du filtrage combinatoire sur la recherche d'issues.
  • Décrire comment l'UI différencie visuellement les deux types.

Le problème concret

Sur une forge Git classique, les labels forment une liste plate par dépôt. Quand vous avez 50 dépôts avec chacun leurs propres labels bug, feature, documentation, vous ne pouvez pas filtrer « toutes les issues de type bug dans tous mes dépôts » sans dupliquer les labels à la main dans chaque dépôt.

De plus, deux équipes qui utilisent le même dépôt veulent des tags libres pour annoter leurs domaines (auth, ci, parser) sans que ces tags exigent une validation préalable par un mainteneur.

L'analogie

Pensez aux tags Flickr à deux niveaux : un album appartient à une catégorie fixe définie par l'organisateur (Voyage, Famille, Travail), et peut recevoir des tags libres ajoutés par quiconque (paris, 2026, coucher-de-soleil). Les deux systèmes coexistent sans se mélanger. La catégorie donne la structure ; les tags libres donnent la granularité.

Le modèle

Deux types, deux scopes

graph TB
    subgraph "Classification labels (scope owner)"
        C1[bug]
        C2[feature]
        C3[documentation]
        C4[security]
    end

    subgraph "Subject labels (scope dépôt)"
        S1[auth]
        S2[parser]
        S3[ci-dagger]
        S4[performance]
    end

    subgraph "Issue #42"
        I1["bug (classification)"]
        I2["auth (subject)"]
    end

    C1 --> I1
    S1 --> I2
Caractéristique Classification Subject
Scope Owner (tous ses dépôts) Dépôt unique
Qui crée Owner, Maintainer uniquement Tout utilisateur connecté
Création inline Non (CRUD dédié /labels) Oui (champ autocomplete dans l'issue)
Style visuel Badge plein (fond coloré) Badge outline (contour coloré)
Couleur Définie par l'auteur Défaut #6b7280, personnalisable
Colonne DB owner_id non-null, repository_id null repository_id non-null, owner_id null

Filtrage combinatoire

L'intérêt principal des classification labels est le filtrage cross-dépôt. Sur le tableau de bord d'Alice (/alice) :

Filtrer par classification: bug
→ Affiche toutes les issues "bug" dans tous les dépôts d'Alice
  (alice/myrepo, alice/api-client, alice/cli-tool)

Un subject label seul ne permet pas ce filtrage car il est scopé à un seul dépôt.

La combinaison des deux offre un filtrage à deux dimensions :

bug (classification) × auth (subject)
→ Toutes les issues bug liées à l'authentification

Assignation sur une issue

La page de détail d'une issue présente deux blocs distincts :

Bloc classification (géré par Owner/Maintainer uniquement) : - Checkboxes pour les labels de classification de l'owner - Bouton « Save labels » - Envoyé dans label_ids[] au POST /{o}/{r}/issues/{num}/labels

Bloc subject tags (géré par l'auteur ou Owner/Maintainer) : - Champ texte avec autocomplete HTMX (déclenché après 3 caractères, délai 300ms) - Tab sur une suggestion → sélectionne le label existant - Tab sur du texte libre → crée le label subject à la soumission (find_or_create_subject) - Badges removable (×) - Envoyé dans subject_names (comma-separated) au même endpoint

Schéma DB

-- Un seul champ label_type discrimine les deux cas
labels (
    id           UUID PK,
    owner_id     UUID NULL,      -- non-null pour classification
    repository_id UUID NULL,     -- non-null pour subject
    name         VARCHAR(50),
    color        VARCHAR(7),
    description  VARCHAR(255) NULL,
    label_type   VARCHAR(20),    -- 'classification' ou 'subject'
    ...
)

-- Index d'unicité composite
UNIQUE(owner_id, repository_id, name, label_type)

La contrainte d'unicité garantit qu'un owner ne peut pas avoir deux labels classification bug, et qu'un dépôt ne peut pas avoir deux subject tags auth.

Alternatives et compromis

Pourquoi pas un seul système de tags libres ? Les tags libres offrent une flexibilité maximale mais aucune standardisation cross-dépôt. Deux développeurs utilisant bug et Bug créent deux labels distincts.

Pourquoi pas des labels en arbre (hiérarchiques) ? Un arbre de labels (comme les tags JIRA avec sous-catégories) serait plus expressif mais beaucoup plus complexe à afficher dans des badges inline. La combinaison classification × subject couvre 95 % des besoins à coût d'implémentation minimal.

Compromis choisi : la classification donne la rigueur (contrôlée par les mainteneurs, partagée cross-dépôt) ; le subject donne la liberté (créé par n'importe qui, spécifique au dépôt). Chacun fait ce que l'autre ne fait pas.

Vérifier votre compréhension

  1. Un développeur crée un subject tag bug dans son dépôt. L'owner a aussi un classification label bug. Comment l'UI les distingue-t-elle visuellement ? Peuvent-ils coexister sur la même issue ?

  2. Alice crée un classification label security sur son compte. Elle a 15 dépôts. Sans aucune action supplémentaire, dans combien de dépôts ce label est-il disponible ?

Pour aller plus loin