Révolutionnez vos projets tech, un ticket à la fois

En coulisse, nous essayons d’améliorer continuellement nos processus de travail et garantir la qualité de nos projets. Pour cela, nous utilisons des outils tels que PHPStan, PHP-CS-Fixer et Rector : Ces outils nous aident à maintenir la cohérence et la qualité de notre code en automatisant les contrôles nécessaires pour assurer sa robustesse et sa conformité aux normes en vigueur. Nous reconnaissons aussi l’importance d’une standardisation dans certains de nos processus de mise en production et de monitoring de projets. Cette standardisation vise à poursuivre l’exécution fluide et sans accroc sur la suite des étapes ⚙️

Plus récemment, nous avons aussi mis en place un « outil qualité », que nous utilisons en interne. Cet outil est le garant d’un suivi de qualité rigoureux, favorisant une gestion et une responsabilisation accrue sur nos projets.

Il pose les bases d’une amélioration constante vers cette excellence opérationnelle, en créant un référentiel qualité organisé par thématique : outillage ; échanges administratifs ; cadrage préliminaire ; travail d’estimation ; accessibilité ; SEO ; performance ; RGPD ; déploiement etc… Maintenant que cet outil est en place à JoliCode et que son utilisation démarre, il est aujourd’hui important d’essayer « d’optimiser » d’autres tâches de notre quotidien, telles que la rédaction de nos tickets (issues) sur GitHub pour les projets clients que nous amorçons. Consacrons donc un peu de temps à clarifier ce processus et à le rendre aussi efficace que possible !

Section intitulée les-benefices-d-un-socle-communLes bénéfices d’un socle commun

GitHub a été initialement conçu avec une grande flexibilité. Néanmoins, le choix délibéré de ne pas adopter de normes a parfois entravé l’efficacité du développement et de la maintenance des projets. Cette situation a incité le service à introduire, à partir de 2016 des modèles de templates qui ont rapidement gagné en popularité.

Pour aller plus loin dans la standardisation et la promotion de bonnes pratiques au sein d’un projet, il est aujourd’hui aussi possible de créer des community health file. Ces fichiers, tels que CONTRIBUTING et CODE_OF_CONDUCT, fournissent en général des conseils et des modèles prédéfinis pour maintenir un projet. En plaçant ces fichiers dans un dossier nommé .github à la racine du dépôt, les mainteneurs de projet peuvent automatiser et standardiser divers aspects du développement et de l’interaction communautaire.

Pour en revenir aux templates, on peut lire dans une étude de 2024 intitulée « An empirical analysis of issue templates usage in large-scale projects on GitHub », que l’utilisation de templates structurés sur un projet entraîne une réduction significative du temps de résolution ainsi qu’une diminution du nombre de commentaires. Ces chiffres soulignent l’impact positif de ces derniers (en tout cas sur des projets open-source à grande échelle).

En adoptant cette approche, les développeurs sont accueillis par un système familier, une structure et des conventions bien établies, ce qui réduit considérablement les frictions lors du passage d’un projet à un autre, ce qui est souvent le cas en agence. Il devient alors plus facile de déléguer des tâches, de partager des idées et de fournir des retours efficaces. Cette communication rationalisée accélère les processus de prise de décision et favorise un sentiment de cohésion et d’alignement entre les membres de l’équipe, indépendamment de leur localisation (télétravail ou non) et de leur niveau d’expertise.

Section intitulée ecrire-un-ticketÉcrire un ticket

Les issues ne se limitent pas à signaler des bugs ; elles sont utiles pour initier des discussions, partager des idées, solliciter des retours et gérer les tâches. En bref, c’est elles qui vont jouer le rôle de guide pour construire et améliorer le projet.

La manière dont nous communiquons à propos du code revêt une importance égale à celle du code lui-même, nos mots ayant le potentiel à la fois d’aider et de nuire à son efficacité. Avec le remote, des systèmes tels que GitHub restent des canaux de communication fondamentaux : il est essentiel de faire preuve de prudence, car l’écrit est parfois le seul point d’appui disponible. Certains termes ou mots peuvent être mal interprétés, même si ce n’était pas l’intention de l’auteur.

Titre : Le titre de la tâche doit être assez descriptif pour que quelqu’un le regardant plus tard comprenne l’objectif et comment elle s’inscrit dans le contexte global (ça commence par là). Nous encourageons l’utilisation d’émojis (car on aime vraiment les émojis), notamment devant le titre, pour indiquer clairement s’il s’agit d’une tâche front-end, back-end, d’un bug, ou liée à l’infrastructure. Des petites choses qui permettent à l’esprit d’avoir une structure et l’engagement nécessaires pour basculer dans un état de concentration favorable ;

Description : Brève description de la tâche nécessaire ou du problème observé, rédigée de manière aussi concise que possible. Pour organiser l’information, il est essentiel de suivre une syntaxe simple comme Markdown.

Ensuite, il convient d’utiliser des champs variables, selon que ce soit un report de bug ou une nouvelle feature, par exemple :

Bugs :

• 👨‍💻 Pour reproduire : Étapes pour reproduire le comportement ;
• 🎯 Comportement attendu : Une description claire et concise de ce à quoi vous vous attendiez ;
• 👀 Captures d’écran/Vidéo : Si applicable, ajoutez des captures d’écran/vidéo pour aider à expliquer votre problème ;
• 💻 Ordinateur : Système d’exploitation : [ex. iOS] ; Navigateur [ex. chrome, safari] ; Résolution [ex. 2560 X 1289] ; Version [ex. 22] ;
• 📱 Mobile/Tablette : Appareil : [ex. iPhone14] ; Système d’exploitation : [ex. iOS17.5] ; Taille de l’écran : [ex. 4.75, 5.5] ; Navigateur mobile [ex. navigateur par défaut, safari] ; Version [ex. 22] ;
• 💡 Contexte additionnel : Ajoutez tout autre contexte sur le problème.

Fonctionnalités :

• 🎯 Résumé : Une explication en un paragraphe de la fonctionnalité ;
• 🗨 Informations : Explication de la fonctionnalité dans son ensemble ;
• 👀 Informations visuelles : Capture d’écran à fournir pour plus de contexte si nécessaire ;
• 💻 Informations techniques : Explication technique à fournir à l’équipe de développement ;
• 🎨 Maquette UI : Liens Figma, ou autre ;
• 🚀 Infrastructure : Si des éléments doivent être indiqués pour l’infrastructure, CRON à prévoir, éléments à lancer depuis l’infrastructure, …

La documentation officielle est toujours bonne à relire et peut vous donner d’autres idées !

Section intitulée idee-pour-ameliorer-encore-votre-templateIdée pour améliorer encore votre template

Les templates peuvent être créés avec Form Schema, une syntaxe YAML qui permet à vos modèles de tickets GitHub de comporter des blocs et du texte pour guider correctement vos contributeurs :

Résultat obtenu :

Section intitulée guider-davantage-le-contributeurGuider davantage le contributeur

Vous pouvez aussi personnaliser le sélecteur de modèles de tickets que les utilisateurs voient lorsqu’ils créent un nouveau ticket dans votre dépôt en ajoutant un fichier config.yml au dossier .github/ISSUE_TEMPLATE. Ces petits changements vous permettront d’ajouter un moyen supplémentaire de les guider vers une source externe importante par exemple.

Le plus important avant et pendant l’écriture d’un ticket est selon nous :

• Faire une recherche efficace pour voir si le sujet a déjà été évoqué. Vous pouvez rappeler ce conseil directement dans le template. Par exemple en insérant un champ « Prerequisites [*] Please check that a similar feature has not already been registered ». Ainsi, la personne ayant créé le ticket pourra ainsi cocher la case « Checked » ;
• Relire son ticket comme si vous étiez un développeur externe. Identifiez les parties qui pourraient manquer de clarté ou de détails et ajoutez les informations nécessaires pour faciliter la compréhension ;
• S’imaginer en charge des modifications décrites dans le ticket. Assurez-vous que les spécifications sont suffisamment détaillées pour guider le travail du développeur.
• Faire en sorte que tous les liens soient cliquables, et non cachés dans des captures d’écrans ;
• De viser l’efficacité en divisant des gros tickets en éléments plus petits

Après son écriture :

• Planifiez régulièrement des sessions de nettoyage pour clore les tickets en souffrance et en créer de nouveaux, parfaitement compréhensibles et à jour. Cela permet de maintenir une gestion efficace tout en évitant de se perdre dans une avalanche de commentaires 🥱 ;
• Mettre régulièrement à jour le ticket en fonction des modifications apportées à la conception, aux délais, aux estimations de travail, etc… ;
• Cherchez à récolter régulièrement des feedbacks de votre équipe concernant la qualité de vos tickets (Daily etc…).

Par ailleurs, il peut être utile de désigner une personne responsable de la « Modération préalable », qui aura le rôle de valider les tickets avant qu’ils ne soient considérés comme acceptés. Il peut examiner chaque problème soumis et fournir un feedback sur la qualité de la rédaction, en demandant des modifications si nécessaire avant d’accepter le problème dans le dépôt.

Pour aller plus loin, vous pouvez utiliser des fonctionnalités telles que le formatage des pull requests pour maintenir une cohérence dans les contributions de votre équipe. De même, l’utilisation de milestones pour définir un roadmap, avec des étapes telles que « Sprint 1 », « Sprint 2 », et ainsi de suite, peut faciliter la planification et le suivi des progrès du projet. Intégrer ces pratiques dans vos projets peut s’avérer également bénéfique.

Section intitulée la-nuance-de-la-flexibiliteLa nuance de la flexibilité

Lorsqu’il s’agit de standardiser l’écriture des tickets sur GitHub, il est crucial de trouver un équilibre entre structure et flexibilité. Nous comprenons l’importance de la clarté et de la cohérence sur une issue, mais nous savons également que chaque projet est unique et nécessite une approche adaptée.

En laissant dès le début la possibilité à l’équipe en charge du projet la liberté de personnaliser les modèles de tickets en fonction des exigences de ce dernier, nous favorisons une approche agile. Cette flexibilité permet non seulement de répondre plus efficacement aux défis et contextes rencontrés, mais elle encourage également la créativité en permettant aux membres de l’équipe de proposer des solutions adaptées à leur expertise (ou sensibilité).

En trouvant le juste équilibre entre structure et flexibilité, nous pouvons maximiser notre efficacité. L’objectif ultime pour toute organisation devrait être de permettre à tous ceux qui utilisent le répertoire du projet de se sentir aussi à l’aise et confiants que possible pour exprimer leurs pensées et demander de l’aide lorsque nécessaire.

Section intitulée conclusionConclusion

La nécessité d’une concentration dans notre travail est importante, et pour en tirer pleinement parti, ainsi que pour en faire bénéficier les autres, il est crucial de normaliser certains aspects. Ces petites optimisations sur le sujet des tickets apportent une fluidité au travail, avec chaque organisation contribuant par ses propres normes issues de son savoir-faire interne, lesquelles évoluent en permanence. Les avantages se manifesteront progressivement à travers une communication plus claire et une résolution plus rapide des problèmes, renforçant ainsi l’adhésion à ces directives.

Poursuivant dans cette voie, il convient de noter que des sujets tels que l’analyse automatique et la prédiction des résultats, ainsi que le rôle des labels par exemple, ont fait l’objet de recherches approfondies et prometteuses, comme en témoignent certains travaux. Des outils tels que le Projet Bee offrent aussi une perspective intéressante en matière d’analyse automatique des rapports de bugs.

Si vous avez déjà mis en place des petites optimisations ou si vous avez des retours d’expérience à nous partager à ce sujet, n’hésitez pas à nous en faire part !