#JaiDécouvert gh-issue-sync.

gh-issue-sync: sync GitHub issues locally and back

gh-issue-sync is a command line tool that syncs GitHub issues to local Markdown files for offline editing, batch updates, and integration with coding agents.

Pull issues locally, refine them until you are satisfied, and sync changes back. Also useful for offline access to your issues.

source

C'est un outil qui répond à un besoin que j'ai depuis 2018 : préparer avec un process précis des issues GitLab ou GitHub en draft, dans un format texte versionnable, particulièrement utile pendant la phase de meta-spec-writing.

C'est pour répondre à ce besoin que j'avais spécifié les fonctionnalités suivantes dans Projet 24 - Prototyper le gestionnaire de projet de mes rêves :

• Permettre d'importer / exporter une ou plusieurs issues dans un format de fichier YAML.
  • Permettre d'importer / exporter ces fichiers via Git.
  • Permettre l'utilisation de branche : création, suppression, merge de branches.
  • Permettre la gestion des branches via l'interface web.
  • Visualisation web des diff entre deux branches.
  • Permettre de commit ou créer des snapshots d'une branche.

source

Je trouve curieux de voir émerger des projets comme Beads en octobre 2025 ou gh-issue-sync en décembre 2025, portés par la mouvance Specs Driven Development des agents IA, alors que j'explore ce formalisme depuis environ 2010. Ce qui m'intrigue surtout : pourquoi les développeurs s'intéressent à la spécification maintenant, et pas avant ? J'ai commencé à rédiger des choses à ce sujet, que je souhaite publier.

---

Le 15 mars dernier, j'ai créé des commandes OpenCode issue-create.md, issue-pull.md, issue-push.md, issue-update.md dont l'objectif était plus ou moins identique à gh-issue-sync : rédiger une issue dans un fichier local, la raffiner, puis l'envoyer vers GitHub. J'ai utilisé ces commandes pour créer les issues du projet sklein-devbox : https://github.com/stephane-klein/sklein-devbox/issues.

En l'état, je ne suis pas satisfait de mon expérience de développeur (DX). Il me semble que la fonctionnalité SKILL.md de gh-issue-sync offre probablement une meilleure architecture que l'utilisation des commandes OpenCode.

Ces prochains jours, je compte tester gh-issue-sync pour un éventuel remplacement. À plus long terme, j'aimerais pousser plus loin le sujet en testant Beads.

Alexandre m'a partagé le chapitre 7 « Bets, Not Backlogs » du livre Shape Up de Basecamp publié en 2019.

Il sait que j'apprécie cette méthode — j'ai lu le livre vers 2021-2022 — et me l'a envoyé parce qu'il ne comprend pas bien comment je peux adhérer à cette méthode alors qu'elle semble aller à l'encontre de ce qu'on a pratiqué ensemble.

Tout d'abord, je commence par préciser que Shape Up semble mélanger les notions de issue tracker et Product Backlog (voir note "Confusion entre issue tracker et backlog, et comment gérer la masse d'issues").

Ensuite, la méthode ne dit pas "no backlog", mais "no backlog commun" :

Des listes décentralisées

On n'a pas à choisir entre un backlog encombrant et ne rien retenir du passé. Chacun peut continuer à suivre pitchs, bugs, demandes ou idées de son côté, sans liste centrale.

Le support peut maintenir une liste des demandes ou problèmes qui reviennent souvent. Le produit suit les idées qu'il espère pouvoir façonner dans un cycle futur. Les développeurs tiennent une liste de bugs qu'ils aimeraient corriger dès qu'ils en ont l'occasion. Il n'y a ni backlog unique ni liste centrale, et aucune de ces listes n'alimente directement le processus des paris.

source

Shape Up ne m'apparaît pas comme une méthode qui interdit de partager des listes d'issues entre sous-groupes — c'est visible quand le texte dit que « le produit suit les idées qu'il espère pouvoir façonner dans un cycle futur » et que « les développeurs tiennent une liste de bugs qu'ils aimeraient corriger dès qu'ils en ont l'occasion ».

Ce qui me semble central dans Shape Up, ce n'est probablement pas tant le rejet d'un issue tracker commun. À mon sens, le cœur de la méthode réside ici :

Quelques paris potentiels

Que fait-on à la place ? Avant chaque cycle de six semaines, on organise une table des paris (betting table) où les parties prenantes décident ce qu'elles vont faire dans le cycle suivant. À cette table, on examine les pitchs des six dernières semaines — ou ceux que quelqu'un a délibérément ressortis et défendus à nouveau.

Rien d'autre n'est sur la table. Pas de longue liste d'idées à passer en revue. Pas de temps perdu à entretenir un backlog d'anciennes idées.

source

Cela signifie que si une issue n'a pas de "sponsor", c'est-à-dire, personne qui la met en avant, alors elle ne sera jamais priorisée. Les pitchs sont examinés à la betting table, mais Shape Up n'a pas de process continu de revue des issues en tant que backlog.

C'est pour moi l'idée la plus importante de ce chapitre par rapport à Scrum "mainstream" et cela ne me perturbe pas, car dans ma pratique Scrum, comme je le disais dans une précédente note, une issue sans sponsor n'a pratiquement aucune chance d'être sélectionnée lors d'un Sprint Planning :

Le triage régulier des issues (fermer et prioriser) est un travail laborieux, extrêmement difficile à maintenir dans la durée dès lors qu'un issue tracker contient beaucoup d'issues. Si je peux témoigner d'une chose, c'est que je n'ai probablement jamais réussi à le faire, ni vu quelqu'un y parvenir.

source

Imaginons un bug remonté il y a 8 mois sur l'export PDF.

• Scénario Scrum classique : le bug traîne dans le backlog, priorité "moyenne". À chaque Sprint Planning, le Product Owner fait défiler la liste, le voit, se dit "pas critique cette fois", et le repousse. Le bug survit parce qu'il est dans le système, pas parce qu'il est défendu.
• Scénario Shape Up : le bug n'existe nulle part dans un backlog central. Si un développeur pense qu'il vaut la peine d'y consacrer un cycle, il doit le re-pitcher activement à la prochaine betting table. Si personne ne le fait, le bug disparaît du radar — pas par décision active de le fermer, mais par absence de sponsor.

Dans ma pratique de Scrum, j'intègre déjà un betting table lors du Sprint Planning, et seules les issues proposées au sprint par un sponsor sont étudiées, par conséquent, cela me semble assez proche de ce que propose Shape Up.

Je préfère Shape Up à Scrum sur ce point précis de la betting table : il me semble que cette approche est plus honnête et reflète probablement mieux ce qui se passe réellement sur le terrain.

À la fin de la note "Collecter les sujets dans un issue tracker pour ne pas se répéter", je disais :

Un backlog est une liste d'items souvent extraits de l'ensemble des issues de l'issue tracker — un sous-ensemble volontairement restreint et de meilleure qualité. Priorisée, maintenue à jour et régulièrement affiné, cette liste représente le travail potentiel sérieusement envisagé pour le produit. Lors du Sprint Planning, les parties prenantes — développeurs, produit et autres contributeurs concernés — discutent et arbitrent ensemble les priorités pour décider quels items intégreront le Sprint Backlog.

source

Est-ce que toutes les issues ouvertes du issue tracker sont un backlog ? La réponse est non.

J'ai vu plusieurs fois des Product Managers arriver dans une organisation et être effrayés par la quantité d'issues présentes dans l'issue tracker — ils essayaient de passer en revue toutes les issues, pensant qu'il s'agissait du backlog.

Il me semble que cette confusion entre issue tracker et backlog est très classique — j'ai moi-même probablement entretenu cette confusion.
Les personnes issues de la culture open source sont habituées aux issue tracker, tandis que les Product Managers sont généralement plus familiers avec les Product Backlog.

Face à toutes ces issues, certains Product Managers font des choix radicaux pour garder la maîtrise :

• fermer très rapidement toutes les issues non prioritaires
• interdire l'utilisation d'un issue tracker
• ignorer l'issue tracker et travailler dans un autre outil

Je ne conseille pas ces approches : elles suppriment d'un bloc ce qui fait la valeur d'un issue tracker (voir "Collecter les sujets dans un issue tracker pour ne pas se répéter").

À la place, je conseille dans un premier temps de ne pas se préoccuper de l'intégralité des issues, et de se concentrer uniquement sur les issues indiquées par ses collègues ainsi que sur celles que l'on a soi-même créées.

Pour suivre ces issues et constituer son backlog, je conseille d'utiliser des labels — sur GitLab, j'utilise par exemple backlog, backlog-stephane, next-sprint, next-next-sprint. Ces labels, combinés à des vues kanban, permettent à chaque membre de créer un backlog à partir d'un sous-ensemble restreint d'issues.

Cette approche par labels fonctionne, mais le problème est que ce workflow exige une rigueur importante et un protocole commun d'équipe — difficile à mettre en place sans un leadership fort qui l'impulse et le maintient.

C'est pour améliorer cette expérience utilisateur, que j'ai intégré les fonctionnalités suivantes dans la description du gestionnaire de projet de mes rêves :

• Permettre de créer des portfolios d'issue par utilisateurs.
• Implémenter un système de tags d'issues personnalisés où chaque utilisateur peut créer ses propres étiquettes. La visibilité de ces tags serait configurable : mode privé pour un usage personnel ou mode partagé pour les rendre disponibles aux autres utilisateurs.

source

De plus, j'imagine aussi une fonctionnalité permettant de « cacher » les issues, ou du moins de les rendre moins facilement accessibles aux nouveaux arrivants — non pas pour en interdire l'accès, mais pour réduire le bruit visuel et éviter qu'ils ne soient effrayés au point, après ce traumatisme, de les ignorer totalement.

Le triage régulier des issues (fermer et prioriser) est un travail laborieux, extrêmement difficile à maintenir dans la durée dès lors qu'un issue tracker contient beaucoup d'issues. Si je peux témoigner d'une chose, c'est que je n'ai probablement jamais réussi à le faire, ni vu quelqu'un y parvenir.

Concernant la fermeture des issues, certains projets configurent un système qui ferme automatiquement les issues après un certain temps sans activité. Personnellement, à la place de cela, je préfère un système qui poste un commentaire dans l'issue qui notifie et demande au créateur s'il juge qu'elle est toujours pertinente. En cas de non réponse après un temps imparti, l'issue peut être clôturée automatiquement.

Pour la priorisation des issues, toujours dans la description du gestionnaire de projet de mes rêves, j'ai imaginé la fonctionnalité suivante :

• Système inspiré de Tinder pour prioriser les issues. L'application présente deux issues choisies selon un algorithme Elo et invite l'utilisateur à désigner celle qu'il considère comme prioritaire.

source

En essayant de répondre à une question d'un ami au sujet du chapitre 7 « Bets, Not Backlogs » du livre Shape Up de Basecamp, j'ai cherché à mettre des mots sur les raisons qui me poussent à utiliser un issue tracker, une pratique que j'expérimente depuis plus de 15 ans. Cette note est le résultat de cette réflexion.

Pendant 5 ans, de 2018 à 2023, j'ai utilisé GitLab comme outil de issue tracker, en équipe, dans deux organisations différentes.

Avant d'aller plus loin, il me semble utile de montrer concrètement les types d'issue présentes dans ces trackers (voir aussi ces labels) :

• Bug — corriger un comportement qui ne correspond pas à ce qui est attendu
• Feature — implémenter une nouvelle fonctionnalité
• Enhancement — améliorer une capacité existante ; DoD : le comportement amélioré est mesurable ou observable
• Knowledge Gap — répondre à une question sans réponse accessible ; DoD : répondre à la question, indiquer comment trouver la réponse à cette question, si l'information n'était pas documentée, alors la documenter ou améliorer la documentation existante
• Spike — explorer une question technique ou une hypothèse incertaine dans un temps imparti ; DoD : du code est livré, une décision binaire est posée (concluante / non concluante) et documentée dans l'issue
• Enabler — préparer le terrain technique pour qu'une ou plusieurs issues futures soient implémentables en moins de 10h ; DoD : mergé sur main sans régression, les issues qu'il débloque sont identifiées
• User story développeur — exprimer un besoin d'infrastructure ou d'outillage interne sous forme de user story dont le "user" est un développeur ; DoD : code produit, environnement de développement amélioré, documentation ajoutée, etc.
• meta-spec-writing — décomposer un périmètre flou en issues actionnables ; DoD : les issues enfants sont créées, estimées et prêtes pour le sprint planning
• Sprint planning — préparer et documenter une session de sprint planning ; DoD : date, participants et issues candidates documentés avant la réunion, décisions prises et issues assignées documentées après
• Sprint retrospective — préparer et documenter une session de rétrospective ; DoD : date et sujets à aborder documentés avant la réunion, décisions et actions correctives documentées après, chaque action corrective génère une issue de suivi

Pourquoi je crée systématiquement une issue ?

Mon approche consiste à créer une issue dès qu'une idée, un bug ou un sujet émerge — même sans intention de le traiter immédiatement.
C'est un point qui me tient à cœur, parce qu'il m'agace profondément de voir les mêmes sujets resurgir sans cesse sans jamais être vraiment travaillés.
J'ai souvent observé dans les open spaces des conversations de 10-20 minutes autour d'un sujet où chacun y va de son opinion, de son intuition, de ses mises en garde et de ses objections, puis retourne à ses activités… pour recommencer le même débat deux jours plus tard. Tout ce qui a été dit est perdu et rarement approfondi.

Ces "conversations de couloir" récurrentes sont un symptôme classique de non-décision : personne ne bloque explicitement, personne n'avance vraiment — la discussion tourne en boucle, invisible et non tracée. Dans certains cas, elles dégénèrent en Stop Energy : les mêmes objections ressurgissent à chaque fois, épuisant le porteur de l'idée sans jamais produire de résolution.

Je préfère de loin créer l'issue avant toute conversation. À défaut, quand j'assiste à une discussion informelle qui tourne en rond, je la crée à chaud, y dépose les idées échangées, et la partage aux participants pour vérifier que j'ai bien retranscrit. La prochaine fois que le sujet resurgit, j'invite chacun à la lire et ajouter son commentaire ou voter "+1".

L'issue devient un espace formel où chacun peut argumenter et enrichir le fil à son rythme ; le Sprint Planning devient le moment de délibération légitime où l'équipe arbitre collectivement si l'issue doit être traitée dans le nouveau sprint ou non.

Cette rigueur n'est pas simple à tenir : quand l'équipe a l'habitude de tout régler à l'oral, créer une issue peut passer pour de la lourdeur bureaucratique. Je la tiens malgré tout, parce que le coût de la répétition me paraît plus élevé que celui du traçage. Surtout, à long terme, cela évite le brouillard organisationnel.

Cette utilisation d'un issue tracker s'inspire du monde du logiciel libre, où des issues peuvent rester ouvertes des années, voire des décennies, et servent de mémoire collective pour comprendre la complexité d'une demande, les trade-offs, les ressources disponibles.

Quand cette méthode est appliquée pendant plusieurs années dans une organisation, un issue tracker peut contenir des centaines voire des milliers d'issues ouvertes, mais ceci ne pose pas de problème car ces issues ne constituent pas un backlog.

Un backlog est une liste d'items extraits et sélectionnés de l'ensemble des issues de l'issue tracker — un sous-ensemble volontairement restreint et de meilleure qualité. Priorisée, maintenue à jour et régulièrement affiné, cette liste représente le travail potentiel sérieusement envisagé pour le produit. Lors du Sprint Planning, les parties prenantes — développeurs, produit et autres contributeurs concernés — discutent et arbitrent ensemble les priorités pour décider quels items intégreront le Sprint Backlog.

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 seul type.

• 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.

• 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

• 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.

• 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

• 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

• 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.

• 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

Voici quelques principes qui me guident. Je pense qu'ils contribuent à rendre une organisation efficace et efficiente.

1. La loi empirique de Gall :

« Un système complexe qui fonctionne se trouve invariablement avoir évolué depuis un système simple qui fonctionnait.
La proposition inverse se révèle également exacte : Un système complexe développé de A à Z ne fonctionne jamais et vous n'arriverez jamais à le faire fonctionner. Vous devez recommencer depuis le début, en commençant par un système simple. »

source

2. Je suis convaincu de la pertinence du modèle de Tuckman pour comprendre comment les équipes se construisent et évoluent au fil du temps. En conséquence, je crois qu'une organisation doit accorder suffisamment de temps aux équipes pour qu'elles atteignent leur phase de performance, puis veiller à maintenir la composition de l'équipe sur la durée.

3. Le modèle du triangle de gestion de projet qui je trouve est très bien expliqué dans le livre Getting Real :

Voici un moyen simple de lancer le projet dans les délais et le budget impartis : ne pas les modifier. Il ne faut jamais consacrer plus de temps ou d'argent à un problème, mais simplement en réduire la taille (le périmètre).

Il existe un mythe qui dit que l'on peut lancer un projet dans les délais, en respectant le budget et le champ d'application. Cela n'arrive presque jamais et, lorsque c'est le cas, la qualité s'en ressent souvent.

Si vous ne pouvez pas tout faire tenir dans le temps et le budget impartis, n'augmentez pas le temps et le budget. Au contraire, réduisez le champ d'application. Il sera toujours temps d'ajouter des choses plus tard - plus tard est éternel, maintenant est éphémère.

Il vaut mieux lancer quelque chose d'excellent dont la portée est un peu plus réduite que prévu que de lancer quelque chose de médiocre et plein de trous parce qu'il fallait respecter une fenêtre magique de temps, de budget et de portée. Laissez la magie à Houdini. Vous avez une véritable entreprise à gérer et un véritable produit à livrer.

source

En mars 2024, je me suis demandé comment utiliser correctement les termes Epic, issue, User Story, Goal, Job Story, Vision, Pitch, Feature, Task, Bug, Spike, Dette technique, Theme.

Voici quelques réflexions à ce propos.

Tout d'abord, tous les artefacts suivants sont des Issues : Epic, User Story, Job Story, Vision, Pitch, Feature, Bug, Spike, Task.

Ensuite, Feature, Bug, Spike et Dette technique indiquent la finalité de l'issue, définissant la nature du travail à réaliser.

User Story et Job Story sont des méthodes de formulation d'issues.

J'ai mis beaucoup de temps à réaliser que les termes Epic, Vision, Theme, Pitch, Goal et Task permettent d'indiquer le niveau d'imprécision d'un objectif.

Exemple allant du flou très prononcé à une version faiblement floue :

• Vision – Le niveau le plus large et abstrait, décrivant une aspiration à long terme.
• Theme – Une direction stratégique regroupant plusieurs objectifs ou Epics.
• Pitch – Une proposition d'idée ou une justification d'un projet, pouvant inclure des objectifs mais restant plus conceptuel.
• Goal – Un objectif spécifique à atteindre, souvent mesurable.
• Epic – Une grande fonctionnalité ou un ensemble de tâches qui contribuent à un objectif plus large.
• Task – Niveau le plus précis, une tâche est une unité de travail concrète et actionnable.

Une ou plusieurs Merge Requests constituent une réponse formelle, exprimée en code, parmi toutes les réponses possibles à une demande formulée dans une issue.
Seule cette réponse formelle, exprimée en code, est véritablement précise. Même l'issue, aussi détaillée soit-elle, conserve toujours une part de flou.

Attention tout de même : quand je dis qu'une issue de type Vision est floue, cela ne veut pas dire que son auteur peut bâcler sa rédaction.
Si, par exemple, la description est limitée à 500 mots, l'auteur doit exploiter au mieux cette limite pour présenter sa vision avec précision. L'objectif n'est pas de créer du flou volontairement, mais plutôt d'exprimer clairement un concept qui, par nature, comporte encore des zones d'incertitude à explorer.

Voici quelques exemples d'issue floue publiés ici :

• 2023-10-28_2008
• Projet 11 - "Première version d'un moteur web PKM"
• 2024-09-07_2240

Une issue, en tant que texte écrit, comporte une part inévitable d'ambiguïté et nécessite donc son auteur pour être défendue :

C’est que l’écriture, Phèdre, a, tout comme la peinture, un grave inconvénient. Les œuvres picturales paraissent comme vivantes ; mais, si tu les interroges, elles gardent un vénérable silence. Il en est de même des discours écrits. Tu croirais certes qu’ils parlent comme des personnes sensées ; mais, si tu veux leur demander de t’expliquer ce qu’ils disent, ils te répondent toujours la même chose. Une fois écrit, tout discours roule de tous côtés ; il tombe aussi bien chez ceux qui le comprennent que chez ceux pour lesquels il est sans intérêt ; il ne sait point à qui il faut parler, ni avec qui il est bon de se taire. S’il se voit méprisé ou injustement injurié, il a toujours besoin du secours de son père, car il n’est pas par lui-même capable de se défendre ni de se secourir.

Phèdre - Dialogue de Platon

Conséquence pratique de tout cela :

• L'auteur d'une issue doit être disponible et accorder du temps à la personne qui va implémenter son issue.
• La personne qui implémente cette issue doit accepter l'imprécision de cette issue. En posant des questions, le développeur doit aider l'auteur à rendre cette issue plus précise.
• L'auteur de l'issue doit accepter de recevoir une implémentation qui ne correspond pas exactement à sa vision… et dans ce cas, il doit soit l'accepter ou accorder plus de temps à cette issue afin d'effectuer plusieurs itérations de correction de l'implémentation.

Ces règles pratiques sont aussi valables lorsqu'une issue est déclinée dans des issues avec un niveau de précision supérieur. Par exemple, lors de la rédaction d'issues de type Epic à partir d'une issue de type Vision.

« Permettre à l'auteur de défendre son texte » ne signifie pas exclusivement un dialogue oral. Ce dialogue peut s'effectuer :

• Par chat synchrone ;
• Par commentaire d'issue asynchrone ;
• Par visioconférence ;
• etc

Je pense que le niveau de précision d'une issue détermine le mode de communication à privilégier. Pour les issues de haut niveau d'abstraction — très floues (Vision, Theme, Pitch), la communication orale se révèle généralement plus efficace, car elle permet des échanges dynamiques et immédiats sur des concepts abstraits.

En revanche, pour les issues plus précises (Tasks, certaines Features), je privilégie une approche asynchrone avec des questions écrites détaillées. Cette méthode offre à l'auteur le temps nécessaire pour réfléchir et affiner sa rédaction. Je ne recours à la communication orale que lorsque des problèmes de compréhension persistent malgré les échanges écrits, afin de débloquer rapidement la situation.

---

Je cherche des solutions pour bien indiquer le niveau de précision des issues que j'écris.

Voici quelques exemples d'introductions d'issues :

Cette issue est de type "vision", c'est donc normal qu'elle soit imprécise. Les zones d'ombre seront affinées progressivement dans des sous-issues spécifiques. Pour clarifier certains aspects, des échanges oraux pourront être organisés afin de répondre à vos questions et d'enrichir cette vision.

Autre exemple :

Cette issue a été rédigée avec un souci particulier de précision. Si vous identifiez des erreurs, des incohérences ou si certains points nécessitent des éclaircissements, n'hésitez pas à les signaler dans les commentaires. Pour toute difficulté de compréhension ou doute persistant, je reste disponible pour organiser une session en visioconférence afin de faciliter nos échanges.

J'ai du mal à bien définir le terme thème en gestion de projet logiciel.

Dans cette note, je vais décrire les deux définitions que je connais.

---

Voici une définition de Ken Rubin, auteur du livre Essential Scrum :

A collection of related user stories. A theme provides a convenient way to indicate that a set of stories have something in common, such as being in the same functional area.

Dans la section glossaire de Essential Scrum

Un Theme peut-être assigné à tout type d'issue, par exemple Epic ou User Story.

---

Les auteurs du livre Product Roadmaps Relaunched ont une autre définition de Theme :

As we’ve touched on, in the relaunched roadmapping process we use themes and subthemes to express customer needs. This is probably a new concept for many of you, so let’s define what we mean by these terms.

Themes are an organizational construct for defining what’s important to your customers at the present time.

...

So, again, themes and subthemes represent the needs and problems your product will solve for. A need is generally something the customer doesn’t have yet, whereas a problem is something that’s not working right (with the existing product, or whatever substitute they might currently be using). Even though these two terms suggest subtle differences, the important point is that both refer to a gap or pain in the customer’s experience. When identifying the themes and subthemes for your roadmap, remember to consider both needs and problems from all angles.

Jared Spool, paraphrasing our very own Bruce McCarthy, says, “Themes help teams stay focused without prematurely committing to a solution that may not be the best idea later on.” As Spool points out, it is important to focus most of the roadmapping effort on customer needs and problems because “the viability of a feature may shift dramatically, while the nature of an important customer problem will likely remain the same.”

Page 124 du livre Product Roadmaps Relaunched

Dans ce livre, un Theme représente un besoin client important à un instant donné.

---

D'après ce que j'ai compris, Product Roadmaps Relaunched adopte une définition plus restrictive du concept de thème que Essential Scrum. Dans Product Roadmaps Relaunched, un thème sert uniquement à décrire des fonctionnalités de façon imprécise.

Exemple tiré du livre Product Roadmaps Relaunched :

• Theme: Billing & payments
  • Subtheme: Billing & payments API integration
  • Subtheme: API integration testing

Pour résumer :

• Essential Scrum inclut des thèmes qui ne sont pas seulement liés aux fonctionnalités, mais aussi à la stratégie globale, à l’organisation, voire aux aspects techniques et processus internes.
• Product Roadmaps Relaunched reste focalisé sur l'expérience utilisateur et les besoins clients, avec des thèmes qui expriment des fonctionnalités sans trop rentrer dans les considérations techniques ou organisationnelles.

---

#JaiDécidé d'adopter la définition de "Theme" donnée dans Essential Scrum.

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 :

• Point à débattre
• Sujet à discuter
• Question Problème

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.

#JaiDécouvert ici le concept de Stop Energy.

https://scaledagileframework.com/enablers/

Voir aussi Issue.

https://scaledagileframework.com/story/

Quelques notes à ce sujet Quelle différence entre une Issue et un Ticket ?

Note d'origine : whatIsStopEnergy

La Stop Energy est un concept formulé par Dave Winer en 2002 pour désigner la force sociale d'obstruction qui s'oppose à toute proposition d'avancement dans une communauté. Là où quelqu'un veut faire avancer les choses (Forward Motion), la Stop Energy agrège les objections de tous ceux qui, quelle que soit la petitesse de leur mise, exercent un droit de veto de fait. Elle n'est pas raisonnée, ne tient pas compte du tableau d'ensemble, et finit toujours par l'emporter — sauf si le porteur du projet l'ignore délibérément. C'est une pathologie bien connue des comités de standardisation, des listes de diffusion open source et de toute gouvernance collective : non pas le débat constructif qui identifie un vrai problème, mais la résistance de principe qui empêche d'avancer sans rien proposer à la place.

Sonnet 4.6