index.md 18KB
title: Collaboration technique slug: collaboration-technique date: 2015-04-14 chapo: Retour sur une formation/accompagnement chez Natural-Solutions.
J’ai eu l’occasion de transmettre et d’accompagner dans la même journée Natural-Solutions sur le thème de « Collaborer efficacement autour du code ». Voici une petite synthèse des échanges et propositions, merci à Olivier et Gilles pour leur confiance. Merci à Vincent pour son accompagnement et sa relecture.
Référentiel commun
What I miss · Most of all, the bug tracker. Any employee can file a bug against any product and be certain that someone on the engineering team will at least look at it. There are certain internal-social-engineering techniques you can use to focus attention on an issue you think isn’t getting enough. Lots of bug reports are feature-requests and others are feature-removal demands, and that’s fine.
*Google + 1yr* (cache)
Il s’agit du conteneur de la valeur technique de l’entreprise. Il est capital de faire un choix stratégique sur ce point et je n’ai pas de solution miracle. À peu près tous les systèmes que j’ai pu tester étaient déficients et contraignants. Il faut au minimum que le système comporte des identifiants uniques et du contenu editable par toutes les parties prenantes. Il vaut mieux qu’il soit pérenne car il est la meilleure source d’investigation des bugs.
En effet, chaque commit doit comporter une référence à la tâche renseignée dans ce référentiel qui documente les raisons d’une telle implémentation. Les messages de commit sont très importants car ils doivent aider vos successeurs lors d’un blame (qui porte assez mal son nom). Le lien est ainsi fait entre chaque ligne de code et chaque développement de fonctionnalité ou correction de bug. Ne pas perdre de vue qu’il faut pouvoir avoir une vue synthétique de ce référentiel (un bon classement (cache) est une aide précieuse).
J’ai de plus en plus tendance à commencer à coder en rédigeant mon message de commit de façon détaillée, cela permet d’avoir les idées claires sur les tenants et les aboutissants avant même de faire la première ligne de code. C’est ce message qui aidera le reviewer et potentiellement l’assurance qualité ensuite. Cela rejoint le Readme Driven Development (cache).
Cas particulier : monorepo
When it comes to repository hosting conversions, I agree with Google and Facebook: I prefer monolithic repositories. When I am interacting with version control, I just want to get stuff done. I don’t want to waste time dealing with multiple commands to manage multiple repositories. I don’t want to waste time or expend cognitive load dealing with submodule, sub repository, or big files management. I don’t want to waste time trying to find and reuse code, data, or documentation. I want everything at my fingertips, where it can be easily discovered, inspected, and used. Monolithic repositories facilitate these workflows more than separate repositories and make me more productive as a result.
J’ai longtemps trouvé cela abscons mais je reviens un peu sur ma position (je ne suis pas prêt à bosser pour Google ou Facebook pour autant…), avoir un dépôt pour l’ensemble des projets peut encourager la collaboration transversalement dans les équipes et le partage de code entre les produits.
Relecture continue
As in Maslow’s pyramid, each layer requires the previous one. It is useless for code that is charging the wrong customer to be readable. Code should be:
- Correct
- Secure
- Readable
- Elegant
- Altruist
L’auto-évaluation est assez mauvaise, on peut relire 15 fois son code et pourtant passer à côté de bugs qui vont être évidents au premier coup d’œil par un pair. Je l’ai expérimenté de nombreuses fois et j’envisage difficilement de me passer d’une telle pratique aujourd’hui. Il faut bien garder à l’esprit que seul le code est évalué, pas la personne. Ça peut faire mal à l’égo mais ce n’est pas une attaque personnelle pour autant !
Les avantages de la review sont nombreux et Anthony et Julien en ont parlé lors de ParisWeb, de même qu’Agnès :
- diffuser la connaissance dans l’équipe
- augmenter la cohérence du code au sein des projets
- partager la responsabilité et son poids
Cas particulier : pair-programming
Si vous êtes 2 dans l’équipe et que vous pair-programmez, qui va relire vos développements ? Est-ce que le fait d’être en paire constitue une relecture suffisante ? Nous avons été confrontés à ce problème avec Mathieu et je n’ai pas d’avis tranché sur la question si ce n’est d’essayer d’avoir une troisième personne dans l’équipe ! Parfois même un collègue sur un autre produit peut être pertinent.
Flux de travail
We don’t want humans waiting on computers. We want computers waiting on humans.
*Notes from Facebook’s Developer Infrastructure at Scale F8 Talk* (cache)
En amont, on établit des conventions de développement (pep8, styleguides, etc) propres à l’équipe et au projet. Il est possible d’automatiser le rendu du code avec JSCS (cache) pour JavaScript ou yapf pour Python par exemple.
- on linte et on teste son code pendant le développement avec les plugins propres à l’éditeur choisi
- on soumet une pull-request bien documentée (cache) (pour du pas à pas (cache))
- on teste sur un environnement aussi proche que possible de la production (possibilité d’utiliser Docker (cache) par exemple)
- on demande une review de son implémentation, on itère et on merge
- on déploie sur un environnement identique à la production qui est testable/montrable
- on déploie en production avec une possibilité de rollback à partir d’un tag explicite
Il est important de conserver une boucle de rétroaction courte (cache) tout au long du flux. Il est possible d’introduire des hooks pour automatiser des tâches (par exemple la création d’issues). Il existe le gitflow bien connu (cache) ou le plus simple github flow (cache), dans tous les cas il est possible d’utiliser des alias (cache) ou des applications dédiées (SourceTree, Tower, Github, etc) pour éviter d’avoir à retenir tout plein de trucs (cache).
Cas particulier : déploiement non-continu
Certains déploiements doivent se produire avec une régularité calendaire ou pour un événement spécial. Dans ce cas, le flux de travail est altéré. Il est important que la pré-production soit vraiment iso-fonctionnelle pour pouvoir effectuer des tests de montée en charge et/ou que la programmation du déploiement puisse être automatisée. Des outils comme Fabric, Chef, Puppet ou Ansible peuvent être utiles pour automatiser les déploiements. Ou juste un script tirant partie des déploiements Github déjà mieux qu’un git pull sur le HEAD de master.
Documentation
What does discoverability and consistency mean? It means producing software (hopefully) free from the artifacts of bias, as agreed upon by your team. Do you have to use Rails or protobuf to be discoverable and consistent? Of course not. But you should seek to gain consensus. Here is a simple guide to becoming more consistent and discoverable in your codebase.
*Consistency* (cache)
La première étape est de documenter l’installation initiale du projet et de réduire celle-ci à 3 étapes (ou moins !). J’ai croisé tellement de projets en open-source qui sont impossibles à installer que ça en est déprimant. Le pire étant que les auteurs se trouvent dans l’incompréhension et sont déçus de n’avoir aucune participation externe… L’optimisation de la prise en main est essentielle à l’intégration de nouvelles personnes sur le projet. Cela doit être votre priorité numéro 1 si vous souhaitez vraiment libérer un produit. Les outils existent pour avoir un poste de développement rapidement (cache), n’hésitez pas à les utiliser (et à les maintenir à jour).
If people are working from the same location, it is important that they do not skimp on writing things down.
Il est très utile également de documenter les décisions techniques stratégiques au cours du cycle de vie d’un projet. C’est le seul moyen de ne pas rediscuter indéfiniment les mêmes choix et de reproduire les mêmes erreurs. C’est peut-être la transition culturelle la plus difficile à effectuer pour une équipe interne qui utilise surtout l’oralité pour les prises de décisions.
Les styleguides sont à la mode et au-delà de l’aspect marketing (cache), il est possible d’avoir une base rapidement qui sert à maintenir la cohérence entre les différents composants d’une application web. Des outils existent pour automatiser sa génération, l’utilisation d’une approche OOCSS/BEM rend les éléments plus simples à isoler/documenter.
J’ai tendance à penser que la dette technique est inévitable (mais je n’ai pas encore pris le temps de lire le bouquin de Bastien sur le sujet ;-)). Partant de ce constat, il y a deux choses à surveiller :
- que la taille du code reste raisonnable en restant le plus pertinent possible sur la valeur apportée à l’utilisateur
- qu’il n’y ait pas de relâchement sur la qualité en cas de rush ou de fatigue, situations où l’on a tendance à débrayer
Cas particulier : The Big Rewrite™
It’s important to remember that when you start from scratch there is absolutely no reason to believe that you are going to do a better job than you did the first time. First of all, you probably don’t even have the same programming team that worked on version one, so you don’t actually have « more experience ». You’re just going to make most of the old mistakes again, and introduce some new problems that weren’t in the original version.
C’est quelque chose que j’ai tenté dans une précédente vie lorsque j’ai réécrit une application de gestion de traçabilité dédiée aux laboratoires. Avec 10 années de recul, je pense que c’était une erreur. Non pas de réécrire mais de ne pas avoir évalué l’inertie du changement de culture associé en interne pour combiner une réécriture ET une simplification.
Si vous prenez cette voie (cache), documentez chaque raison de la réécriture et chaque décision prise au cours de celle-ci.
Discussion
Read the Docs, sadly, is still heavily dependent on me being around to operate it. Our campaign to make it more sustainable is the first step towards hopefully fixing this situation. Operating and supporting the site has started to take most of my time, not leaving much room for building community and on boarding contributors. In fact, it leads to an implicitly hostile environment for new contributors, because nobody was around to help them, test their patches, and get changes into the codebase.
La matinée de formation a été suivie d’une après-midi d’accompagnement qui nous a permis de mettre en application un workflow de travail basé sur git(hub) pour encourager les revues de code et les participations externes.
J’en retiens trois discussions, la première sur le financement de l’open-source où il a été question de développement à base de crowdfounding, voire de companyfounding pour mutualiser les coûts ? Cela m’a rappelé la discussion que nous avions eue avec Simon lors de MousTIC sur le financement des communs (cache).
La seconde portait sur la gestion de l’inclusion de modules non open-source dans un projet open-source, je n’ai pas de solution pour cela à part essayer de faire une architecture qui permet l’inclusion de plugins mais cela reste limité. Si vous avez des suggestions/expériences je suis preneur.
Enfin, la dernière était relative à l’inclusion des contributeurs externes sur un projet open-source, en plus de la documentation d’installation du projet déjà évoquée, j’ai proposé :
- documenter pourquoi est-ce que le projet a été mis en open-source et quelles sont les attentes au niveau des contributions
- documenter comment est-ce que le projet peut recevoir des améliorations (quel workflow, quels tests, quelle réactivité)
- identifier clairement des bugs qui sont faciles à prendre pour rentrer dans le projet
- proposer d’avoir une position de mentor sur certains bugs pour accompagner les débutants
- discuter de manière ouverte les décisions et les orientations du projet avec la communauté
C’est un travail fastidieux qui ne porte ses fruits que sur le long terme et dont le retour sur investissement est difficilement quantifiable (recrutement, renommée, etc). Mais quelle joie pour l’équipe lorsque ça prend ! L’ensemble de ces réflexions m’ont amené à écrire un gabarit de README pour projets open-source encourageant la participation. N’hésitez pas à contribuer ;-).
Each developer in your company should have two days per month to work on the open source software your product is built on.
[…]
The real reason you should do it is because it will make your product better, make your developers better, and make your company a more attractive place to work.
Au final, c’était un plaisir d’accompagner une équipe dans sa recherche de pertinence autour de ses produits open-source, j’espère vraiment que l’on pourra inscrire cette relation de confiance dans la durée.