POSS Chap 4 Part 3
Un article de Framalang Wiki.
[modifier] Writing It All Down
At some point, the number of conventions and agreements floating around in your project may become so great that you need to record it somewhere. In order to give such a document legitimacy, make it clear that it is based on mailing list discussions and on agreements already in effect. As you compose it, refer to the relevant threads in the mailing list archives, and whenever there's a point you're not sure about, ask again. The document should not contain any surprises: it is not the source of the agreements, it is merely a description of them. Of course, if it is successful, people will start citing it as a source of authority in itself, but that just means it reflects the overall will of the group accurately.
This is the document alluded to in the section called “Developer Guidelines” in Chapter 2, Getting Started. Naturally, when the project is very young, you will have to lay down guidelines without the benefit of a long project history to draw on. But as the development community matures, you can adjust the language to reflect the way things actually turn out.
Don't try to be comprehensive. No document can capture everything people need to know about participating in a project. Many of the conventions a project evolves remain forever unspoken, never mentioned explicitly, yet adhered to by all. Other things are simply too obvious to be mentioned, and would only distract from important but non-obvious material. For example, there's no point writing guidelines like "Be polite and respectful to others on the mailing lists, and don't start flame wars," or "Write clean, readable bug-free code." Of course these things are desirable, but since there's no conceivable universe in which they might not be desirable, they are not worth mentioning. If people are being rude on the mailing list, or writing buggy code, they're not going to stop just because the project guidelines said to. Such situations need to be dealt with as they arise, not by blanket admonitions to be good. On the other hand, if the project has specific guidelines about how to write good code, such as rules about documenting every API in a certain format, then those guidelines should be written down as completely as possible.
Tout mettre par écrit
Arrivé à un certain point, le nombre de conventions et d'accords tacites entourant votre projet risque de devenir si important qu'il deviendra nécessaire de les consigner quelque part. Pour donner à ce document sa légitimité faites savoir qu'il est basé sur les discussions menées sur la liste et sur des accords qui ont déjà cours. Lors de sa rédaction, veillez à faire référence aux fils pertinents dans les archives de la liste de diffusion et s'il y a des points sur lesquels vous avez des doutes, reposez la question. Le document ne doit renfermer aucune surprise : il n'est pas la source des accords, mais leur description. Certes, s'il est réussi, les gens commenceront à le citer comme une référence, mais cela voudra simplement dire qu'il reflète avec exactitude la volonté générale du groupe.
La section intitulée "Les directives développeurs" dans le Chapitre 2, Bien démarrer fait allusion à ce document. Évidemment, quand le projet est tout jeune il faut mettre par écrit les lignes directrices sans que l'on puisse s'appuyer sur la longue histoire du projet. Mais au fur et à mesure que la communauté de développement mûrit vous pourrez adapter le discours pour refléter l'évolution du projet.
N'essayez pas d'être exhaustif. Aucun document ne peut contenir tout ce que les gens ont besoin de savoir pour participer à un projet. Parmi les conventions que génère un projet, un bon nombre restent souvent inexprimées ou ne sont jamais mentionnées explicitement et pourtant tout le monde les respecte. D'autres encore sont tout bêtement trop évidentes pour être mentionnées et ne feraient que détourner l'attention des éléments importants pas aussi évidents. Par exemple, il est inutile d'écrire des directives telles que "Soyez poli et respectueux sur les listes de discussion et ne lancez pas de trolls" ou "Écrivez du bon code dépourvu de bogues." Bien sûr, ces comportements sont souhaitables, mais comme il n'existe pas d'univers concevable où ils ne le seraient pas ce n'est pas la peine de les mentionner. Si les gens sont grossiers sur les listes ou s'ils écrivent du code bogué, ils ne vont pas cesser de le faire simplement parce que c'est écrit dans les directives du projet. Ces situations doivent être traitées lorsqu'elles se présentent et non par des incitations génériques. D'un autre côté, si le projet a des directives spécifiques pour écrire du code de qualité, telles que les règles pour documenter chaque API dans un certain format, alors ces directives devraient être mises par écrit de manière aussi complète que possible.
A good way to determine what to include is to base the document on the questions that newcomers ask most often, and on the complaints experienced developers make most often. This doesn't necessarily mean it should turn into a FAQ sheet—it probably needs a more coherent narrative structure than FAQs can offer. But it should follow the same reality-based principle of addressing the issues that actually arise, rather than those you anticipate might arise.
If the project is a benevolent dictatorship, or has officers endowed with special powers (president, chair, whatever), then the document is also a good opportunity to codify succession procedures. Sometimes this can be as simple as naming specific people as replacements in case the BD suddenly leaves the project for any reason. Generally, if there is a BD, only the BD can get away with naming a successor. If there are elected officers, then the nomination and election procedure that was used to choose them in the first place should be described in the document. If there was no procedure originally, then get consensus on a procedure on the mailing lists before writing about it. People can sometimes be touchy about hierarchical structures, so the subject needs to be approached with sensitivity.
Perhaps the most important thing is to make it clear that the rules can be reconsidered. If the conventions described in the document start to hamper the project, remind everyone that it is supposed to be a living reflection of the group's intentions, not a source of frustration and blockage. If someone makes a habit of inappropriately asking for rules to be reconsidered every time the rules get in her way, you don't always need to debate it with her—sometimes silence is the best tactic. If other people agree with the complaints, they'll chime in, and it will be obvious that something needs to change. If no one else agrees, then the person won't get much response, and the rules will stay as they are.
Two good examples of project guidelines are the Subversion hacking.html file, at http://svn.collab.net/repos/svn/trunk/www/hacking.html, and the Apache Software Foundation governance documents, at http://www.apache.org/foundation/how-it-works.html and http://www.apache.org/foundation/voting.html. The ASF is really a collection of software projects, legally organized as a nonprofit corporation, so its documents tend to describe governance procedures more than development conventions. They're still worth reading, though, because they represent the accumulated experience of a lot of Open Source projects.
Un bon moyen de déterminer ce qui doit figurer dans le document est de se fonder sur les questions les plus courantes des nouveaux venus, ainsi que sur les récriminations les plus courantes des développeurs expérimentés. Ceci ne veut pas forcément dire que le document doit prendre la forme d'une FAQ, il nécessitera vraisemblablement une structure narrative plus cohérente que ne le permet une FAQ. Mais il devrait suivre le même principe : traiter des questions qui se posent réellement plutôt que celles qui d'après vous pourront se poser.
Si le projet est une dictature bienveillante ou dispose de cadres investis de pouvoirs spéciaux (président, directeur ou autre), alors le document est également une bonne occasion pour codifier les procédures de succession. Parfois ceci se résume simplement à la désignation de personnes particulières pour remplacer le DB au cas où celui-ci quitterait brusquement le projet pour une raison quelconque. Généralement, si DB il y a, il est le seul qui peut nommer un successeur. S'il y a des cadres élus, alors la procédure de nomination et d'élection qui a servi à les désigner à l'origine devrait être décrite dans ce document. Si aucune procédure n'existe, cherchez le consensus via la liste de discussion avant de la mettre par écrit. Les gens sont parfois très chatouilleux en matière de hiérarchie, c'est pourquoi le sujet doit être abordé avec tact.
Mais le plus important est peut-être de dire clairement que les règles peuvent être révisées. Si les conventions décrites dans le document commencent à entraver le projet rappelez bien à tout le monde que ledit document est censé être un portrait vivant des intentions du groupe et non une source de frustration et de blocage. Si quelqu'un prend l'habitude de demander à tout bout de champs la révision des règles chaque fois que les règles se mettent en travers de son chemin vous n'êtes pas obligé d'en débattre sans arrêt, garder le silence est parfois une bonne tactique. Si d'autres personnes sont d'accord avec ces critiques ils s'en mêleront et il deviendra évident que quelque chose doit changer. Mais si personne d'autre n'est d'accord, alors il n'y aura pas de réaction et le règlement restera tel quel.
Deux bons exemples de directives de projet sont : le "Hacker's Guide" de Subversion (http://svn.collab.net/repos/svn/trunk/www/hacking.html) et les documents de gouvernance de l'Apache Software Foundation (http://www.apache.org/foundation/how-it-works.html et http://www.apache.org/foundation/voting.html). L'ASF est en réalité une collection de projets logiciels ayant un statut juridique d'organisme à but non lucratif, ses documents tendent donc à décrire des procédures de gouvernance plutôt que des conventions de développement. Cela vaut néanmoins la peine de les lire car ils représentent l'expérience accumulée au cours de nombreux projets Open Source.
81.57.208.69 10 avril 2007 à 19:54 (CEST)
