larlet-fr-david/david/blog/2015/collaboration-technique/index.md

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](/david/blog/2015/formations-explorations/) et [d’accompagner](/david/pro/accompagnement/) dans la même journée [Natural-Solutions](http://www.natural-solutions.eu/) 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 al­l, the bug track­er. Any em­ploy­ee can file a bug against any prod­uct and be cer­tain that some­one on the en­gi­neer­ing team will at least look at it. There are cer­tain internal-social-engineering tech­niques you can use to fo­cus at­ten­tion on an is­sue you think isn’t get­ting enough. Lots of bug re­ports are feature-requests and oth­ers are feature-removal de­mand­s, and that’s fine.
> 
> <cite>*[Google + 1yr](https://www.tbray.org/ongoing/When/201x/2015/03/29/Anniversaries)* ([cache](/david/cache/cd48ce5c2d83f8fa7b4c0a957db0d333/))</cite>

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](https://github.com/davidbgk/git-style-guide) 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](https://robinpowered.com/blog/best-practice-system-for-organizing-and-tagging-github-issues/) ([cache](/david/cache/986d37a75df767708b9e348e71b07345/)) 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](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) ([cache](/david/cache/053cc2e6338158d83f898d2d0f5912a8/)).


### 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.
>
> <cite>*[On Monolithic Repositories](http://gregoryszorc.com/blog/2014/09/09/on-monolithic-repositories/)* ([cache](/david/cache/7baab90810027d42259e14006a420074/))</cite>

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
>
> <cite>*[Maslow’s pyramid of code review](http://blog.d3in.org/post/111338685456/maslows-pyramid-of-code-review)* ([cache](/david/cache/b6f259d122890a04a89b658b364f62cd/))</cite>

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é](http://julienw.github.io/parisweb-2014-bonnes-pratiques/html5/parisweb-2014-bonnes-pratiques.html) lors de ParisWeb, de même [qu’Agnès](http://www.paris-web.fr/2014/conferences/100-de-revue-de-code.php) :

* 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](http://agopian.info/blog/) 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.
>
> <cite>*[Notes from Facebook’s Developer Infrastructure at Scale F8 Talk](http://gregoryszorc.com/blog/2015/03/28/notes-from-facebook%27s-developer-infrastructure-at-scale-f8-talk/)* ([cache](/david/cache/add9aea6059be55754097cf61bd9eee2/))</cite>

En amont, on établit des conventions de développement ([pep8](https://www.python.org/dev/peps/pep-0008/), [styleguides](https://github.com/citrusbyte/styleguides/), etc) propres à l’équipe et au projet. Il est possible d’automatiser le rendu du code avec [JSCS](https://medium.com/@addyosmani/auto-formatting-javascript-code-style-fe0f98a923b8) ([cache](/david/cache/cfdfe70dc1d0b6d3a9695c5dd3610b3e/)) pour JavaScript ou [yapf](https://github.com/google/yapf) pour Python par exemple.

1. on *linte* et on teste son code pendant le développement avec les plugins propres à l’éditeur choisi 
2. on soumet une *pull-request* [bien documentée](https://quickleft.com/blog/pull-request-templates-make-code-review-easier/) ([cache](/david/cache/e9b8e370e7a0b08985827431c82f1d85/)) (pour [du pas à pas](https://gun.io/blog/how-to-github-fork-branch-and-pull-request/) ([cache](/david/cache/87088098369e5eadca6728c963966792/)))
3. on teste sur un environnement aussi proche que possible de la production (possibilité d’[utiliser Docker](https://realpython.com/blog/python/docker-in-action-fitter-happier-more-productive/) ([cache](/david/cache/37adabe90396072db9cfdd99baa61cd0/)) par exemple)
4. on demande une *review* de son implémentation, on itère et on *merge*
5. on déploie sur un environnement identique à la production qui est testable/montrable
6. 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](http://mathieu.agopian.info/blog/latence-et-boucle-de-retroaction.html) ([cache](/david/cache/f1ed7d7dff2ed14214bdf7a25dde1d74/)) tout au long du flux. Il est possible d’introduire des *hooks* pour automatiser des tâches (par exemple [la création d’issues](https://github.com/naholyr/github-todos/wiki/Full-presentation)). Il existe le [gitflow bien connu](http://www.occitech.fr/blog/2014/12/un-modele-de-branches-git-efficace/) ([cache](/david/cache/7dfecff06cb91feccce15d23301c09e8/)) ou le [plus simple github flow](http://scottchacon.com/2011/08/31/github-flow.html) ([cache](/david/cache/5669f09e770c1bae1f4a84a753eff260/)), dans tous les cas il est possible d’[utiliser des alias](http://haacked.com/archive/2014/07/28/github-flow-aliases/) ([cache](/david/cache/d69a335a5162c7bf71aa35b2e7ec73a7/)) ou des applications dédiées (SourceTree, Tower, Github, etc) pour éviter d’avoir à retenir [tout plein de trucs](http://www.git-attitude.fr/2014/09/15/30-options-git-qui-gagnent-a-etre-connues/) ([cache](/david/cache/1cad71d948ab1aee73e88a73a0112df4/)).


### 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](http://www.fabfile.org/), Chef, Puppet ou Ansible peuvent être utiles pour automatiser les déploiements. Ou juste [un script](https://github.com/remind101/deploy) tirant partie des [déploiements Github](https://developer.github.com/v3/repos/deployments/) 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.
>
> <cite>*[Consistency](http://localshred.github.io/consistency.html)* ([cache](/david/cache/60d8082d551627ee8c83c1d7da9b4213/))</cite>

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](http://agileek.github.io/docker/2015/04/13/docker-ansible/) ([cache](/david/cache/1f566c364ea0d8e96da00f38ecb08651/)), 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.
>
> <cite>*[The Remote Manifesto](https://about.gitlab.com/2015/04/08/the-remote-manifesto/)* ([cache](/david/cache/b51c1c6daa60f39f6d088712176d766f/))</cite>

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](http://styleguides.io/) sont [à la mode](http://primercss.io/) et au-delà de [l’aspect marketing](https://medium.com/@operatino/living-style-guide-tools-in-depth-overview-28cfffb92d05) ([cache](/david/cache/ff9dd5355d2a5b57988ebcfbd74f77b3/)), 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](https://trulia.github.io/hologram/) [existent](https://github.com/kneath/kss) pour [automatiser](http://jacobrask.github.io/styledocco/) sa génération, l’utilisation d’[une approche OOCSS/BEM](http://www.alsacreations.com/article/lire/1641-bonnes-pratiques-en-css-bem-et-oocss.html) 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](http://boutique.letrainde13h37.fr/products/la-dette-technique-bastien-jaillot) 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. 
>
> <cite>*[Things You Should Never Do, Part I](http://www.joelonsoftware.com/articles/fog0000000069.html)* ([cache](/david/cache/136e6aaaf23c95e360dcf6428dade480/))</cite>

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](http://blog.aelogica.com/development/rewrite-not-question/) ([cache](/david/cache/effe69ce88eb3a3bc286767b15197de3/)), 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.
>
> <cite>*[Making Read the Docs Sustainable](http://ericholscher.com/blog/2015/apr/10/making-read-the-docs-sustainable/)* ([cache](/david/cache/bb89afe29cd75835fd7df428b44b9759/))</cite>

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](http://simons.fr/) lors de [MousTIC](http://moustic.info/2015/wakka.php?wiki=PagePrincipale) sur [le financement des communs](http://unisson.co/fr/wiki/prestation/) ([cache](/david/cache/817d232d98ee6c2e5f266582c3c47628/)).

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](https://github.com/davidbgk/open-source-template) 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.
>
> <cite>*[The Two Day Manifesto](http://twodaymanifesto.com/)* ([cache](/david/cache/73fc8424bbfbf91a8f75db7060a24aea/))</cite>


Au final, c’était un plaisir d’accompagner une équipe dans sa recherche de pertinence autour de [ses produits](https://github.com/NaturalSolutions) *open-source*, j’espère vraiment que l’on pourra inscrire cette relation de confiance dans la durée.