À mesure que l'industrie mûrissait, plusieurs changements liés se sont produits en même temps. La jungle des normes matérielles a progressivement permis l'émergence de quelques lauréats : lauréats grâce à une meilleure technologie, une meilleure stratégie voire la combinaison des deux. En même temps, et pas entièrement par hasard, le développement de langages de programmation dits de « haut niveau » signifiait que l'on pouvait écrire un programme une seul fois, dans un langage, et le voir automatiquement traduit (compilé) pour qu'il puisse fonctionner sur différents types d'ordinateurs. Les constructeurs de matériel n'ont pas manqué de voir les implications : un client pouvait, dès ce moment, entreprendre un travail considérable d'ingénierie logicielle sans s'enchaîner nécessairement à une architecture particulière. Ceci, couplé à une diminution des écarts de performances entre les différents ordinateurs (les conceptions les moins performantes étant évincées), faisait qu'un fabriquant qui misait tout sur le matériel pouvait s'attendre à voir baisser ses marges dans un futur proche. La puissance brute des ordinateurs n'était plus suffisante pour créer un avantage décisif, la concurrence s'est alors déplacée sur le terrain des logiciels. Vendre des logiciels, ou au moins leur donner la même importance qu'au matériel, devenait la nouvelle stratégie gagnante.

Cela signifiait que les fabricants devaient commencer à faire respecter le droit d'auteur sur leur code de manière plus stricte. Si les utilisateurs continuaient à partager et modifier le code de manière libre entre eux, ils pourraient reproduire certaines des améliorations désormais vendues en tant que « valeur ajoutée » par le fournisseur. Pire encore, le code partagé pourrait tomber entre les mains des concurrents. L'ironie est que tout ceci se passait à l'époque où Internet commençait à pointer son nez. Alors même que les obstacles au partage de logiciels tombaient, la mue du marché des ordinateurs l'a rendu économiquement indésirable, au moins du point de vue de n'importe quelle entreprise. Les fournisseurs ont renforcé leurs positions, soit en refusant aux utilisateurs l'accès au code faisant fonctionner leurs machines, soit en imposant des accords de confidentialité rendant tout partage impossible.

Sans faire une liste de tous les projets et de toutes les licences, on peut dire qu'à la fin des années 80, il existait de nombreux logiciels disponibles sous une grande variété de licences. La diversité des licences reflétait une diversité équivalente des motivations. Même certains des programmeurs choisissant la GNU GPL n'étaient pas aussi déterminés idéologiquement que le projet GNU lui-même. Et s'ils appréciaient de travailler sur des logiciels libres, de nombreux développeurs ne considéraient pas les logiciels propriétaires comme un mal social. Quelques personnes ressentaient un besoin moral de débarrasser le monde des « logiciels panneaux d'affichage » (appellation de Stallman pour les logiciels propriétaires), mais d'autres étaient plutôt motivées par l'émulation technique ou le plaisir de travailler avec des collaborateurs partageant leurs idées, voire même, par le simple désir humain de gloire. Pourtant généralement, ces diverses motivations n'interagissaient pas de manière destructive. C'est en parti dû au fait que les logiciels, contrairement à d'autres œuvres créatives comme la prose ou les arts visuels, doivent réussir des tests semi-objectifs pour être considérés comme des succès : ils doivent fonctionner et ne pas trop comporter de bogues. Cela donne aux participants du projet une base commune, une raison et un cadre pour travailler ensemble sans trop se préoccuper des qualifications autres que techniques.

Les développeurs avaient une autre raison de rester unis : il s'est avéré que le code produit par le monde des logiciels libres était de très bonne qualité. Dans certains cas, ils étaient notablement techniquement supérieurs à leur équivalent non-libre le plus proche, dans d'autres cas ils étaient au moins comparables, et bien sûr, toujours meilleur marché. Alors que seulement quelques personnes auraient pu être motivées pour produire des logiciels libres sur des bases strictement philosophiques, bien plus l'étaient du fait des meilleurs résultats obtenus. De plus, il y avait toujours, parmi les utilisateurs, un certain pourcentage prêt à faire don de leur temps et de leurs compétences afin d'aider à entretenir et améliorer le logiciel.

Cette tendance à produire du bon code n'était certainement pas universelle, mais cela se produisait à une fréquence croissante dans les projets de logiciels libres du monde entier. Les entreprises tributaires de logiciels commencèrent progressivement à le remarquer. Beaucoup d'entre elles découvrirent qu'elles utilisaient déjà, sans le savoir, des logiciels libres pour leurs opérations quotidiennes (les dirigeants ne sont pas toujours au courant des choix de leur service informatique). Les sociétés entreprirent de s'impliquer davantage dans les projets de logiciels libres en mettant à disposition du temps et des équipements, voire même en finançant le développement. De tels investissements pouvaient, dans les meilleurs scénarii, se montrer très lucratifs par un coefficient de retour conséquent. Le commanditaire ne paie qu'un nombre réduit de programmeurs experts pour se consacrer à plein temps au projet, mais récolte les fruits de la collaboration de chacun, y compris du travail des bénévoles et des développeurs payés par d'autres sociétés.

Alors que le monde de l'entreprise prêtait de plus en plus attention aux logiciels libres, les programmeurs se trouvèrent confrontés à de nouveaux problèmes de représentation. L'un d'entre eux était le mot « free » lui-même. Entendant pour la première fois « free software », nombre de personne pensait, à tort, que cela signifiait « logiciel gratuit ». S'il est vrai que tous les logiciels libres ne coûtent rien,^[7], tous les logiciels gratuits ne sont pas libres. Par exemple, durant la bataille des navigateurs dans les années 90 et dans la course aux parts de marché qu'ils se livraient, Netscape et Microsoft offraient leurs navigateurs Web gratuitement. Aucun des deux n'était libre dans le sens des « logiciels libres ». Vous ne pouviez pas obtenir le code source et, même si vous y parveniez, vous n'aviez pas le droit de le modifier ni de le redistribuer ^[8] Vous pouviez tout juste télécharger un exécutable et le lancer. Les navigateurs n'étaient pas plus libres que les logiciels sous film plastique achetés en magasin : tout au plus étaient-ils diffusés à prix inférieur.

La confusion sur le mot « free » est entièrement due à l'ambivalence malheureuse du terme en anglais. La plupart des autres langues font une distinction entre la notion de prix et de liberté (la différence entre gratuit et libre est évidente pour ceux parlant une langue romane par exemple). Mais l'anglais étant de facto la langue d'échange sur Internet, le problème spécifique à cette langue concerne, à un certain degré, tout le monde. L'incompréhension liée au mot « free » était telle que les programmeurs de logiciels libres ont fini par créer une formule en réponse : « C'est free (libre) comme dans freedom (liberté), pensez à free speech (liberté de parole), pas à free beer (bière gratuite) ». Reste que devoir l'expliquer sans cesse est fatigant. De nombreux programmeurs ressentaient, à juste titre, que l'ambiguïté du mot « free » rendait plus difficile la compréhension par le public de ce type de logiciels.

Cependant, le problème apparaissait plus profond que cela. Le mot « libre » était vecteur d'une connotation morale indéniable : si la liberté était une fin en soi, peu importait que les logiciels libres soient également meilleurs ou plus profitables à certaines sociétés dans certaines circonstances. Ce n'étaient là que les effets secondaires bienvenus d'une motivation qui, au fond, n'était ni technique ni commerciale mais morale. En outre, l'idée « Libre comme dans liberté » imposait une flagrante contradiction aux sociétés souhaitant soutenir certains logiciels libres dans un domaine particulier de leurs activités, mais voulant continuer à commercialiser des logiciels propriétaires dans d'autres branches.

Ces dilemmes touchèrent une communauté déjà promise à une crise d'identité. Les programmeurs qui écrivent des logiciels libres n'ont jamais réussi à se mettre d'accord sur le but final, s'il existe, du mouvement des logiciels libres. Même dire que les opinions vont d'un extrême à l'autre serait trompeur, car cela implique une vision linéaire au lieu de la dispersion multidimensionnelle existante. Cependant, on peut définir deux grands courants de pensée, si vous acceptez de passer outre les détails pour le moment. L'un des groupes partage la pensée de Stallman que la liberté de partager et modifier est la plus importante, et qu'en conséquence, si vous cessez de parler de liberté, vous abandonnez l'idée principale. Pour d'autres, c'est le logiciel qui compte et ils ne se voient pas dire que les logiciels propriétaires sont par définition mauvais. Certains programmeurs de logiciels libres, mais pas tous, pensent que l'auteur (ou l'employeur dans le cas de travail rémunéré) devrait avoir le droit de contrôler les termes de la distribution et qu'aucun jugement moral ne devrait été rattaché au choix de termes particuliers.

Pendant longtemps personne n'a vraiment eu à prêter attention à ces différences ou à leurs interférences, mais le succès grandissant des logiciels libres dans le monde de l'entreprise a rendu cette question inévitable. En 1998, le terme Open Source a été inventé, en tant qu'alternative à « libre », par une coalition de programmeurs devenue par la suite The Open Source Initiative (OSI).^[9]. Pour l'OSI non seulement le terme « logiciel libre » était déroutant, mais le mot « libre » n'était qu'un symptôme d'un problème plus général : le mouvement avait besoin d'une stratégie de commercialisation pour s'adapter au monde de l'entreprise, et les discours sur les avantages moraux et sociaux du partage ne pénètreraient pas les conseils des sociétés. Selon eux :

La pointe de l'iceberg de la polémique apparaît dans ce texte. Il mentionne « nos convictions » mais évite intelligemment de citer précisément quelles sont ces convictions. Pour certains, ça peut être la conviction que le code développé selon un processus ouvert sera meilleur, pour d'autres ça peut-être la conviction que toutes les informations devraient être partagées. L'usage du mot « vol » fait (sûrement) référence à la copie illégale, dont beaucoup se défendent : ce n'est pas un vol si personne n'est dépossédé de son bien. On retrouve aussi le raccourci facile, mais injuste, entre logiciels libres et anti-capitalisme, sans débattre du bien fondé de cette accusation.

Rien de tout cela ne signifie que le site de l'OSI est incomplet ou trompeur. Il ne l'est pas. Au contraire, c'est la vitrine de ce qui manquait au mouvement du logiciel libre d'après l'OSI : une bonne stratégie commerciale où « bon » veut dire : « viable dans le monde des affaires ». L'Open Source Initiative a offert à beaucoup de gens exactement ce qu'ils cherchaient : un vocabulaire pour parler des logiciels libres avec un plan de développement et une stratégie commerciale, plutôt qu'une croisade idéologique.

Mettez vous à la place d'une personne qui aurait entendu parlé de votre projet pour la première fois, peut être après l'avoir découvert à l'issue d'une laborieuse recherche de solution à sa problématique. Le premier contact avec le projet se fera au travers de son nom.

Un bon nom ne fera pas systématiquement le succès d'un projet, pas plus qu'un mauvais son échec (un très mauvais y conduira mais nous pouvons supposer que personne ne tente de faire échouer son propre projet volontairement). Néanmoins, un mauvais nom peut ralentir l'adoption d'un projet, soit parce que les gens ne le prennent pas au sérieux, soit parce qu'il est difficile à mémoriser.

Un bon nom:

Une fois que le site Web a été trouvé, la seconde chose que les visiteurs font en général est de rechercher une courte description du projet ou de sa finalité pour déterminer (en moins de trente secondes) s'ils désirent ou non en savoir plus. Cet abstract doit être clairement visible au sein de la page de garde du site, de préférence juste sous le nom du projet.

La description doit être concrète, concise et, par dessus tout, courte. Voici un exemple à suivre :

En quelques mots, les points principaux sont révélés tout en s'appuyant largement sur les connaissances actuelles du lecteur. En précisant "en tant que communauté", ils affirment qu'aucun organisme privé ne dominera le développement ; "international" signifie que le logiciel permettra aux utilisateurs de travailler dans différentes langues et données régionalisées ; "toutes les plates-formes majeures" ajoute qu'il sera portable sous Unix, Macintosh, et Windows. Le reste signale que les architectures interopérables et les formats ouverts forment une part importante des principes directeurs du projet. Il n'est pas explicitement dit que ce projet est une alternative à la suite bureautique Microsoft Office mais la plupart des visiteurs auront lu entre les lignes. Même si cette description peut sembler quelque peu verbeuse au première abord, elle s'avère en fait exhaustive : les mots "suite bureautique" sont concrets pour les utilisateurs familiers de ce type de logiciel, on s'appuie sur la connaissance présumée du lecteur (probablement au tant qu'utilisateur de MS Office) pour assurer la concision du message.

La description des finalités dépend en partie de son auteur, pas seulement du logiciel en tant que tel. Dans l'exemple précédent d'OpenOffice.org, il est utile d'utiliser les mots "en tant que communauté" car le projet était initialement principalement porté par Sun Microsystems. En précisant ainsi la nature du projet, Sun indique qu'il est sensible à la crainte qu'il puisse dominer le processus de développement et la feuille de route. De cette façon, en exposant clairement la prise en compte du problème, c'est une grande partie du problème lui-même qui disparaît. De leur coté, les projets qui ne sont pas soutenus par un unique organisme n'aura probablement pas à appuyer sur cet aspect puisque le mode de développement communautaire est la norme dans ce domaine, il n'y a donc pas d'impératif à le lister comme élément des principes directeurs.

Les visiteurs toujours intéressés après avoir consulté les finalités désirerons ensuite obtenir d'avantage de détail, peut être le guide utilisateur ou de développement, et voudront éventuellement télécharger quelque chose. Mais ils doivent d'abord avoir la certitude qu'il s'agit d'un logiciel libre.

La page de garde doit indiquer sans ambiguïté que le projet est libre. Ceci peut sembler évident mais vous seriez surpris du nombre de projets qui oublient de le mentionner. J'ai déjà vu des projets dont la page de garde non seulement ne mentionnait pas la licence sous laquelle le projet était distribué mais pas même qu'il était libre. Quelque fois, cette information cruciale est reléguée dans la page de Téléchargement ou la page réservée aux développeurs, voire à d'autres endroits nécessitant plus d'un clic de souris à atteindre. Dans des cas extrêmes, la licence n'est pas donnée du tout et le seul moyen de l'obtenir est de télécharger le logiciel et de regarder à l'intérieur.

Ne commettez pas cette erreur qui peut coûter des développeurs et utilisateurs potentiels. Affichez clairement, juste sous les finalités, que le projet est "libre" ou "open source" et précisez la licence exacte. Un guide de prise en main rapide pour choisir une licence est donnée dans la section intitulée « Choisir une licence et la mettre en oeuvre » plus loin dans ce chapitre, et les questions de licences sont discutées en détail dans le Chapitre 9, Licenses, Copyrights, and Patents.

A cette étape, notre visiteur a déterminé -probablement en moins d'une minute- s'il est suffisamment intéressé pour dépenser, disons, cinq minutes de plus à approfondir ce projet. Les paragraphes suivants décrivent ce qui devrait rencontrer durant ces cinq minutes supplémentaires.

Il s'agit d'une courte liste des fonctionnalités principales du logiciel (si des fonctions ne sont pas encore opérationnelles, vous pouvez les lister à condition de préciser "prévu" ou "en cours"), ainsi que l'environnement technique nécessaire à son exécution. Imaginez cette liste de fonctionnalités/pré-requis comme ce que vous répondriez à quelqu'un vous demandant un bref résumé du logiciel. Cette liste est une extension naturelle des finalités. Par exemple, pour cette mission :

La liste fonctionnalités/pré-requis fournirait les détails afin de clarifier cette mission.

Disposant de ces informations, les visiteurs peuvent rapidement déterminer si ce logiciel leur convient. Ils peuvent également décider ou non de proposer leurs services en tant que développeurs.

Les gens apprécient toujours de connaître l'état d'un projet. Pour les nouveaux projets, ils veulent connaître le fossé entre les promesses et la réalité courante. Pour les projets mâtures, c'est l'activité de maintenance qui les intéresse : fréquence de nouvelles versions, réactivité face aux tickets d'incidents, etc.

Pour répondre à toutes ces questions, il est conseillé de fournir une page de statut du développement listant les objectifs du projet à court terme et ses besoins (par exemple, il peut rechercher un développeur disposant d'une expertise particulière). Cette page fournit également un historique des versions antérieures, munie d'une liste de fonctionnalités, pour que les visiteurs puissent se faire une idée de ce que le projet appelle "avancement" et à quelle vitesse effective il correspond.

Ne craignez pas de paraître en plein chantier et ne vous laissez pas tentés par un enjolivement du statut. Tout le monde sait qu'un logiciel évolue par paliers; il n'y a aucune honte à affirmer "Ceci est un logiciel en alpha avec des bogues connus. Il démarre et fonctionne la plupart du temps mais utilisez-le à vos risques et périls". Un tel langage ne rebute pas le type de développeurs dont vous avez besoin à cette étape. De même, du coté des utilisateurs, il n'y a rien de pire que de les attirer avant que le logiciel soit prêt pour eux. Une réputation d'instabilité est très difficile à rattraper une fois acquise. L'humilité paye sur le long terme : il est toujours préférable pour un logiciel d'être plus que moins stable qu'attendu et les bonnes surprises assurent le bouche à oreille.

Le logiciel devrait être distribué en code source dans un format standard. Lorsqu'un projet démarre, les distributions de binaires (exécutables) ne sont pas obligatoires à moins que le projet possède tant de dépendances ou de pré-requis de compilation que le faire fonctionner nécessite un effort considérable. (Mais dans ce cas, le projet aura des problèmes à recruter des développeurs de toute manière !)

La procédure d'installation doit être aussi simple, standard et peu économe en ressource que possible. Si vous tentez d'éradiquer une maladie, vous ne distribueriez pas le médicament de façon à qu'il nécessite une seringue de taille non standard pour être administré. De la même façon, les logiciels doivent se conformer à des standards de construction et d'installation; plus ils dévient du standard, plus d'utilisateurs et de développeurs abandonnent, perplexes.

Cela semble évident mais beaucoup de projets ne daignent standardiser leur procédure d'installation que très tard dans le projet, se disant qu'ils auront l'occasion de le faire à tout moment: "Nous verrons l'empaquetage lorsque le code sera mieux fini". Ce qu'ils ne réalisent pas est qu'en mettant de coté ce travail rébarbatif, ils allongent en réalité la phase de réalisation du code, parce qu'il découragent les développeurs qui -sinon- y auraient contribué. De façon plus insidieuse, ils ne savent pas qu'ils perdent tous ces développeurs car il s'agit d'une accumulation de non-événements : quelqu'un visite le site Web du projet, télécharge le logiciel, tente de le compiler, échoue dans cette entreprise et s'en va. Qui saura que cela s'est produit, excepté la personne elle-même ? Personne du projet ne réalisera que cette motivation et cette compétence a été gaspillée.

Le travail ennuyeux avec un bon retour sur investissement devrait toujours être réalisé tôt pour abaisser suffisamment la barrière d'accès au projet.

Lorsque vous publiez une version téléchargeable, il est vital de lui donner un numéro de version unique pour que les gens puissent comparer deux versions et savoir immédiatement laquelle précède l'autre. La numérotation de version est discutées au paragraphe la section intitulée « Release Numbering », et les détails de la standardisation des procédures de compilation et d'installation sont détaillés dans la section intitulée « Packaging » et Chapitre 7, Packaging, Releasing, and Daily Development.

Télécharger les distribution de sources est satisfaisant pour simplement installer et utiliser le logiciel, mais n'est pas suffisant pour déboguer ou ajouter de nouvelles fonctionnalités. Les extractions de sources journalières sont utiles, mais pas d'une fréquence adéquate pour favoriser l'émergence d'une communauté de développeurs. Les gens ont besoin d'accéder en temps réel aux sources dans leur état courant et le moyen de leur offrir ce service est d'utiliser un système de Gestion de Configuration Logicielle (GCL). Le fait de fournir un accès anonyme aux sources en GCL est un signe -à la fois dirigé vers les utilisateurs et vers les développeurs- que ce projet fait un effort particulier pour fournir aux gens ce dont ils ont besoin pour participer. Même si vous ne pouvez proposer la GCL tout de suite, laissez une indication que vous allez le faire sous peu. L'infrastructure de gestion de configuration logicielle est développée en détail dans la section intitulée « Les logiciels de gestion de versions » du Chapitre 3, L'infrastructure technique.

Il en va de même de la gestion de tickets. Son importance ne réside pas seulement dans son utilité pour les développeurs mais également pour les observateurs du projet. Pour beaucoup, la mise à disposition d'une base de donnée d'incidents est l'un des indicateurs les plus forts du sérieux d'un projet. D'ailleurs, la qualité apparente d'un projet est directement proportionnelle au nombre de tickets saisis. Ceci peut semble contradictoire mais gardez à l'esprit que le nombre de bogues dépend de trois choses : le nombre absolu de bogues inclus dans le logiciel, le nombre d'utilisateurs du logiciel, et la facilité avec laquelle les utilisateurs peuvent reporter leurs incidents. Sur ces trois facteurs, les deux derniers sont les plus significatifs. Tout logiciel d'une certaine taille et complexité contient un nombre indéterminé de bogues attendant d'être découverts. La vraie question est de savoir comment le projet gère l'enregistrement et la priorisation de ces tickets. Un projet avec une base d'incidents importante et correctement gérée (les bogues sont pris en compte rapidement, les doublons sont identifiés, etc..) donne une meilleure impression qu'un projet dénué de gestion de tickets ou doté d'une base de donnée quasiment vide.

Bien entendu, votre projet contiendra au départ peu de bogues, et il n'y a pas à s'en inquiéter. Si la page de statut met l'accent sur la jeunesse du projet et que les gens observant la base de bogues constatent que la plupart des incidents sont récents, ils pourront en conclure que le projet possède un bon niveau d'enregistrement de tickets et ne seront pas excessivement alarmés par le faible nombre absolu de tickets enregistrés.

Notez que les outils de gestion de ticket ne sont pas seulement utilisés pour suivre les incidents mais également les demandes de fonctionnalités, les évolutions de la documentation et bien d'autres choses encore. Nous ne détaillons pas davantage la gestion de ticket car ce point est développé dans la section intitulée « Bug Tracker » du Chapitre 3, L'infrastructure technique. Du point de vue de la présentation du projet, l'important est de posséder un outil de gestion de tickets et de s'assurer que ce fait est visible dès la page de garde du site Web.

Les visiteurs apprécient de savoir comment joindre les personnes responsables du projet. Fournissez les adresses des listes de diffusion, des chambres de discussion (chat), les canaux IRC et autres forums où les personnes liées au projet sont accessibles. Précisez clairement que vous et les autres auteurs du projet sont inscrits sur ces listes de diffusion afin que les utilisateurs constatent qu'il existe un moyen simple de contacter les développeurs. Notez que votre présence sur les listes n'implique pas de répondre à toutes les questions ou d'implémenter toutes les demandes de fonctionnalités. Sur le long terme, la plupart des utilisateurs n'utiliseront pas ces canaux de toute manière, mais ils seront rassurés de savoir qu'il pourraient le faire en cas de besoin.

Dans les prémisses du projet, il n'y a pas de besoin à séparer les forums utilisateurs et développeurs. Il est nettement préférable que ces deux populations se parlent l'une à l'autre, dans une seule "pièce". Parmi les utilisateurs de la première heure, la distinction est floue entre développeurs et utilisateurs. Le ratio développeurs sur utilisateurs est en général bien plus élevé à cette étape que plus tard dans le projet. Bien que vous ne puissiez compter chaque utilisateur comme quelqu'un désirant travailler sur votre projet, vous pouvez estimer qu'une bonne partie est intéressée pour suivre les discussions sur le développement comme moyen de saisir la direction du projet.

Ce chapitre traitant seulement à ce stade de la façon de démarrer un projet, il est suffisant de dire que ces canaux de communications doivent exister. Plus loin, dans la section intitulée « Handling Growth » du Chapitre 6, Communications, nous étudierons comment où et comment monter de tels forums, les façon de les gérer ou de les modérer, et comment séparer les forums utilisateurs et développeurs, lorsque le temps est venu, et sans créer un fossé infranchissable.

Quelqu'un cherchant à contribuer au projet commencera par rechercher le guide du développeur. Ces guides sont davantage sociaux que techniques : ils expliquent comment les développeurs interagissent les uns avec les autres et avec les utilisateurs, et au final comment les choses se font.

Ce sujet est couvert en détail dans la section intitulée « Writing It All Down » du Chapitre 4, Social and Political Infrastructure, mais le contenu général du guide du développeur est le suivant :

A propos, il n'y a pas de sous-entendu péjoratif au mot "dictature". C'est tout à fait acceptable de fonctionner en mode tyrannie où un développeur particulier a un droit de veto sur toute modification. Beaucoup de projets fonctionnent de cette manière avec succès. L'important est que le projet l'exprime clairement et au grand jour. Une tyrannie prétendant être une démocratie fera fuir les gens ; une dictature se présentant comme telle fonctionnera bien aussi longtemps que le dictateur est compétent et possède la confiance de l'équipe.

Voir http://subversion.apache.org/docs/community-guide/ pour un exemple de guide du développeur particulièrement exhaustif, ou http://www.openoffice.org/dev_docs/guidelines.html pour un exemple de guide plus large se concentrant d'avantage sur la gouvernance et l'esprit du projet et moins sur les considérations techniques.

Le sujet distinct de fournir une introduction à la programmation du logiciel est discutée dans la section intitulée « La documentation développeurs » plus loin dans ce chapitre.

La documentation est essentielle. Il doit exister quelque chose même si c'est rudimentaire et incomplet. C'est encore une tâche à classer dans la catégorie "déplaisant" déjà évoquée plus tôt et qui est souvent le premier écueil pour les projets libres. Définir des finalités et une liste de fonctionnalités, choisir une licence, synthétiser un statut d'avancement - tout ceci constituent des tâches plutôt légères et souvent faites une fois pour toutes. La documentation, de son coté, n'est jamais réellement achevée et c'est peut être la raison pour laquelle les gens rechignent quelque fois à son écriture.

L'effet le plus insidieux est que l'usage de celui qui écrit la documentation est l'exact inverse de celui qui la consulte. Le contenu documentaire le plus important pour les utilisateurs initiaux comprend les choses les plus élémentaires : comment installer rapidement le logiciel, un aperçu de la façon dont il fonctionne et, peut être, des guides pour réaliser les tâches les plus courantes. C'est précisément les éléments que les auteurs connaissent parfaitement, si bien qu'il est très difficile pour eux d'acquérir le point de vue des utilisateurs, puis de détailler laborieusement des étapes leur semblant évidentes au point d'être inutiles à mentionner.

Il n'existe pas de solution toute prête à ce problème. Quelqu'un doit simplement s'asseoir et démarrer quelque chose, puis de le faire lire par des utilisateurs lambda pour tester sa qualité. Utilisez un format simple, facile à éditer comme le HTML, le texte brut, Textinfo ou des variantes de XML : quelque chose de léger et permettant des mises à jours rapides et au fil de l'eau. Ce critère ne concerne pas seulement la productivité de l'auteur original mais également à long terme de ceux qui joindront le projet plus tard et qui désireront maintenir cette documentation.

Une façon simple de s'assurer que la documentation initiale sera réalisée est de limiter son périmètre à l'avance. Un bon moyen de le déterminer est de s'assurer qu'il respecte les critères minimaux suivants:

Le dernier point est fondamental et peut s'appliquer au projet dans sa globalité et pas seulement la documentation. Une énumération détaillée des problèmes connus est la norme dans le monde du libre. Nul besoin d'exagérer les défauts du projet, il s'agit simplement de les identifier scrupuleusement et dépassionné lorsque le contexte le requiert (par exemple dans la documentation, l'outil de gestion de tickets ou sur une liste de diffusion). Personne ne le prendra comme du défaitisme ni comme un engagement à résoudre les problèmes à une date butoir, sauf si le projet l'exprime explicitement. Puisque tous les utilisateurs peuvent découvrir des incident par eux-même, il est nettement préférable pour eux d'être préparés psychologiquement : ainsi le projet donnera une image de bonne gestion.

Si le projet propose une interface graphique ou produit un artéfact distinctif, mettez en avant des exemples sur le site Web du projet. Dans le cas d'une IHM, il s'agit de captures d'écrans; pour les artéfacts, il peut s'agir également de captures d'écrans ou de fichiers bruts. Dans les deux cas, vous assurez une gratification instantanée : une simple capture d'écran est plus convaincante que des paragraphes de description ou de bavardages sur les listes de diffusion, car une capture d'écran est la preuve sans ambiguïté que le logiciel fonctionne. Il peut être bogué, difficile à installer, être insuffisamment documenté, mais cette capture est la preuve qu'il est possible de le faire fonctionner, à condition d'y mettre un effort suffisant.

Certains sites proposent un hébergement gratuit et une infrastructure pour les projets libres : une zone Web, un outil de gestion de configuration logiciel, un outil de gestion de ticket, des référentiels de téléchargement, des forums de discussion, des sauvegardes automatiques, etc. Les détails varient d'un site à l'autre, mais les mêmes services de base sont offerts par tous. En utilisant l'un de ces sites, vous obtiendrez beaucoup gratuitement, mais vous perdrez, bien entendu, le contrôle fin sur l'expérience utilisateur. La forge décide quelle logiciel le site utilise, et peut contrôler ou au moins influencer l'aspect des pages Web.

Voir la section intitulée « Canned Hosting » du Chapitre 3, L'infrastructure technique pour plus de détail sur les avantages et inconvénients des forges, ainsi qu'une liste des sites qui offrent ces services.

Si vous ne voyez pas d'objections à ce que votre code soit potentiellement utilisé dans les logiciels propriétaires, utilisez une licence MIT/X ou dérivées. Il s'agit de la plus simple de plusieurs licences minimalistes qui n'apporte pas grand chose de plus que la mention du copyright (sans restriction du droit de copie) et la spécification explicite que le produit est utilisé sans garantie d'aucune sorte. Voir la section intitulée « The MIT / X Window System License » pour plus de détail.

Si vous ne désirez pas que votre code puisse être utilisé dans des programmes propriétaires, utilisez la GNU General Public License (http://www.gnu.org/licenses/gpl.html). La GPL est assurément la licence libre la plus largement reconnue dans le monde actuellement. C'est un net avantage, puisque les utilisateurs et contributeurs y sont familiarisés, et ne dépenseront donc pas de temps supplémentaire à lire et comprendre votre licence. Voir la section intitulée « The GNU General Public License » du Chapitre 9, Licenses, Copyrights, and Patents pour davantage de précisions.

Une fois la licence choisie, vous devez la préciser sur la page Web de garde du projet. Nul besoin d'inclure le texte de la licence à cet endroit; fournissez simplement le nom de la licence, et prévoyez un lien vers la licence complète située sur une autre page.

Vous explicitez ainsi quelle licence vous prévoyez d'utiliser pour le logiciel, mais c'est insuffisant en terme juridique. Le logiciel lui même doit en effet contenir la licence. La façon standard de le mettre en oeuvre et d'incorporer un fichier texte de licence nommé COPYING (ou LICENSE), et d'ajouter une courte notice dans l'entête de chaque fichier source, fournissant la date du copyright, le détenteur, la licence et pour finir l'endroit ou le texte complet de la licence peut être obtenu.

Il y a bien des variantes possibles, nous fournissons donc un unique exemple ici. La licence GNU GPL requiert d'ajouter une telle notice en entête de chaque fichier source :

Copyright (C) <année>  <nom de l'auteur>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Cette notice ne spécifie pas explicitement que la copie de la licence que l'utilisateur reçoit avec le logiciel se trouve dans le fichier COPYING, mais c'est en général l'endroit utilisé (vous pouvez modifier l'entête pour le spécifier directement). Elle fournit également une adresse géographique à partir de laquelle demander une copie de la licence. Une autre méthode commune est de fournir un lien vers une page Web comprenant le texte de la licence. Utilisez simplement votre jugement et pointez vers l'endroit le plus adéquat pour obtenir une copie de façon permanente, ce qui peut être n'importe où sur votre site Web. En général, la notice que vous utilisez n'aura pas exactement le contenu de l'exemple plus haut. L'important est d'y faire figurer les données obligatoires : détenteur du copyright, date, nom de la licence et moyen d'accès au texte de la licence.

Même après avoir rendu le projet publique, vous et les autres fondateurs serez souvent tentés de résoudre les questions complexes en petit comité via un canal privé. C'est spécialement vrai au début du projet, alors qu'il y a tant de décisions importantes à prendre et, en général, si peu de volontaires qualifiés pour les prendre. Tous les inconvénients évidents des listes de discussion publiques vont alors apparaître de façon très palpable : le délai inhérent aux conversations par courriel, le besoin de réserver suffisamment de temps pour qu'un consensus se forme, l'embarras à devoir répondre aux volontaires naïfs qui pense comprendre tous les problèmes mais qui ne les comprennent pas (tous les projets ont ce genre de personnes ; quelques fois elles sont les contributeurs stars de l'année d'après, quelque fois ils restent naïfs ); ceux qui ne comprennent pas que vous désirez seulement résoudre le problème X alors qu'il leur semble évident que ce problème est un sous-ensemble d'un problème Y, et ainsi de suite. La tentation de prendre des décisions toutes portes fermées et de les présenter comme faits accomplis, ou au moins comme de fermes recommandations d'un groupe de votants uni et influent, est en effet très grande.

Ne le faites pas.

Aussi longues et lourdes que ces discussions publiques puissent paraître, elles sont presque toujours préférable sur le long terme. Prendre d'importantes décisions en privé est comme utiliser un repoussoir à contributeurs sur votre projet. Aucun volontaire sérieux ne restera dans un environnement ou un conseil secret prend toutes les décisions importantes. En outre, les discussions privées ont des effets de bord bénéfiques en plus de la simple résolution d'un éphémère problème technique :

Enfin, il faut mettre dans la balance la possibilité que quelqu'un sur la liste fasse une réelle contribution à la conversation. C'est difficile de dire si c'est probable, tout dépend de la complexité du code et du degré de spécialisation requis. Mais, si vous permettez l'anecdote, je suppute que c'est plus probable qu'on peut le penser intuitivement. Sur le projet Subversion, nous (les fondateurs) étions en face de ce que nous croyions être un ensemble de problèmes complexes et profonds, sur lesquels nous avions réfléchi dur depuis des mois, et nous doutions franchement que quelqu'un sur la nouvelle liste de diffusion puisse apporter une contribution utile à la discussion. Alors, nous avons emprunté la voie de la facilité et nous avons commencé à batailler sur des idées techniques via des courriels privés, jusqu'à ce qu'un observateur du projet ^[10] présenti ce qui ce passait et demanda que la discussion soit déplacée sur la liste publique. Nous le fîmes, un peu à reculons il est vrai, et nous furent sidérés par le nombre de commentaires pertinents et par les suggestions qui en ont résultées. Dans de nombreux cas, les gens apportèrent des idées qui ne nous étaient jamais venues à l'esprit. Il apparut qu'il y avait des gens très pointus sur cette liste ; ils étaient simplement à attendre le bon appât. Il est vrai que les discussions qui ont suivies prirent plus de temps que si la conversation était restée privée, mais elles furent tellement plus productives que cela justifiait largement cette rallonge.

Sans descendre aux généralités telle que "le groupe est toujours meilleur que l'individu" (nous avons tous rencontré suffisamment de groupes pour le savoir), nous pouvons mettre l'accent sur le fait que les groupes excellent vraiment dans certaines activités. La revue par pair massive est une ; générer un grand nombre d'idées en est une autre. La qualité des idées dépend de la qualité intellectuelle des contributeurs, bien entendu, mais vous ne connaissez pas le type de penseurs auquel vous vous adressez avant de les avoir stimulés avec un problème coriace.

Bien sûr, certains discussions doivent rester privées, ce livre en donnera des exemples. Mais le principe directeur devrait être : s'il n'y a pas de vrai raison pour que ce soit privé, ça doit être publique.

Y arriver requiert des actions effectives. Il n'est pas suffisant de s'assurer que vos propres messages vont dans une liste publique, vous devez aussi guider les conversations inutilement privées des autres vers la liste. Si quelqu'un démarre une discussion privée, et qu'il n'y aucune raison que cette discussion reste privée, c'est à vous d'ouvrir une méta-discussion immédiatement sur la liste. Ne commentez même pas le sujet initial tant que vous n'avez pas déplacé la conversation dans un endroit publique, à moins de vous assurer que la confidentialité est requise. Si vous procédez de la sorte sur le long terme, les gens saisiront le message assez rapidement et utiliseront la liste publique par défaut.

Vous devez assurer une politique de tolérance zéro contre les comportements agressifs ou insultants, et ce dès les tous premiers message de la liste publique du projet. La tolérance zéro ne signifie pas de prendre des mesures automatiques. Vous n'avez pas, par exemple, à supprimer quelqu'un de la liste de diffusion quand il attaque un autre contributeur, ou de lui enlever le droit de commit parce qu'il a tenu des propos déplacés (en théorie, vous pouvez éventuellement en arriver là, mais seulement après que tous les autres moyens aient échoués -ce qui n'est pas le cas, par définition, lorsque le projet démarre). La tolérance zéro signifie simplement qu'aucun mauvais comportement ne demeurera sans réponse. Par exemple, si quelqu'un envoi un message mélangeant un commentaire technique avec une attaque ad hominem envers un autre développeur du projet, il est impératif que vous répondiez à l'attaque ad hominem en premier et dans une question spécifique, et seulement après à la question technique.

Il est malheureusement très facile, et régulier, que les discussions constructives dérivent en de véritables pugilats. Les gens ont tendance à dire par courriel ce qu'il ne diraient jamais face à face. Le sujet de discussion amplifie seulement cet effet : dans un débat technique, les gens pensent souvent qu'il n'y a qu'une bonne réponse à une question donnée, et que tout désaccord avec cette réponse peut seulement s'expliquer par l'ignorance ou la stupidité de celui qui l'exprime. Il n'y a qu'un pas entre qualifier de stupide la proposition technique de quelqu'un et le qualifier de stupide lui-même. Il est en fait souvent difficile de déterminer ou fini le débat et ou commence l'attaque personnelle ; c'est la raison pour laquelle les réponses drastiques ou les punitions ne sont pas une bonne idée. Lorsque vous pensez que le débat s'envenime, envoyez plutôt un message mettant l'accent sur l'importance de conserver la discussion amicale, sans accuser quiconque d'être délibérément agressif. De tels messages de "bonne conduite" ont néanmoins tendance à sonner comme une leçon de maîtresse de maternelle :

Bien que pompeux, ce style de réponse a un effet non négligeable. Si vous reprenez avec constance les débordements, mais sans demander de faire ou de d'accepter des excuses, vous laisser aux gens la possibilité de garder la tête froide et de montrer leur meilleur jour en se comportant de façon plus appropriée la fois suivante. Un des secrets est de ne jamais faire de cette méta-discussion le sujet principal. Elle doit toujours être traitée séparément, comme préface dans votre réponse. Notifiez en passant que "les choses ne se traitent pas de cette manière ici", mais retombez tout de suite sur le sujet initial pour laisser la possibilité aux gens de répondre quelque chose en rapport. Si quelqu'un proteste qu'il ne mérite pas votre réprimande, refusez simplement de répondre à cette escalade. Vous pouvez soit ne pas répondre (si vous pensez qu'il s'agissait simplement d'un accès d'humeur), soit dire que vous êtes désolé si vous avez réagit trop vivement et qu'il est difficile de percevoir toutes les nuances dans un courriel, puis revenez au sujet principal. N'insistez jamais pour exiger des excuses, que ce soit de façon publique ou privée, de quelqu'un qui s'est mal comporté. C'est une bonne chose s'il décide de son propre chef d'envoyer une excuse, mais en exiger ne cause que du ressentiment.

L'étiquette doit être reconnue comme l'un des comportements du groupe. Cela aide le projet car les développeurs peuvent être dissuadés de participer (même des projets sur lesquels ils aimeraient travailler) par les polémiques. Vous pouvez même ne jamais vous en rendre compte; quelqu'un peut scruter la liste, constater qu'il faut être armé d'une cuirasse pour participer au projet, et donc décider de ne pas s'y investir du tout. Garder les forums amicaux est une question de vie ou de mort sur le long terme, et c'est bien plus facile à faire tant que le projet est encore jeune. Une fois que l'étiquette rentre dans les moeurs, vous n'aurez plus à être le seul à la promouvoir, elle le sera par tous.

L'une des meilleurs bonnes pratiques pour favoriser le développement d'une communauté productive est de permettre aux gens d'observer leur code les uns les autres. Un peu d'infrastructure technique est requise pour y arriver, en particulier il faut activer l'envoi de courriels sur commit (voir la section intitulée « Commit emails » pour plus de détails). Le but est d'émettre un courriel contenant les annotations et les changements (diff) de chaque commit de code (voir Diff du la section intitulée « Vocabulaire de la gestion de versions »). La revue de code est la pratique consistant à consulter ces courriels au fil de l'eau en y recherchant des bogues ou de possibles améliorations.^[11]

La revue de code répond simultanément à plusieurs objectifs. Il s'agit de l'exemple le plus évident de revue par pairs dans le monde du libre, et elle aide à assurer un bon niveau de qualité au logiciel. Chaque bogue incorporé dans la version finale l'a été parce qu'il n'a pas été détecté à temps ; ainsi, plus d'yeux observent les commits, plus le nombre de bogues sera limité. Mais ce processus sert aussi un autre but plus indirect : il conforte les gens dans l'idée que ce qu'ils font a de l'importance, puisqu'il est évident que personne ne prendrait le temps de faire une revue s'il ne se souciait de son effet sur le programme. Les gens produisent leur meilleur travail quand ils savent que d'autres l'évalueront.

Les revues doivent être publiques. Même lorsque j'ai été assis avec d'autres développeurs dans la même pièce physique, et que l'un d'entre nous avait fait un commit, nous prenions garde à ne pas faire la revue verbalement, mais de l'envoyer plutôt sur la liste. Tout le monde profite de cette revue. Les gens suivent les commentaires et quelque fois y découvrent des erreurs, et même si ce n'est pas le cas, cela leur rappelle que la revue est une activité régulière, comme laver la vaisselle ou tondre la pelouse.

Dans le projet Subversion, la revue de code n'a pas été initialement un exercice régulier. Il n'y avait aucune garantie que chaque commit serait revu, même on pouvait consulter une modification si elle se trouvait dans notre champs d'action. Les bogues se glissaient sans difficulté alors qu'ils aurait pu et auraient du être filtrés. Un développeur nommé Greg Stein, qui connaissait la valeur de la revue par pair d'un ancien travail, décida qu'il allait montrer l'exemple en faisant la revue de chaque commit arrivant dans le référentiel. Chaque modification était rapidement suivie d'un courriel de Greg envoyé à la liste développeur dans lequel il disséquait le commit, analysait les problèmes potentiels, et proposait quelque fois un peu de code bien tourné. Instantanément, il attrapa des bogues et des méthodes de programmation non optimales qui autrement auraient glissées sans que personne ne s'en rende compte. Il est à noter qu'il ne s'est jamais plaint d'être le seul à faire ces revues, même s'il y consacrait une quantité de temps importante. Il en chantait simplement les louanges dès qu'il le pouvait. Assez rapidement, d'autres personnes, moi compris, commencèrent à l'imiter. Quelle était notre motivation ? Non pas que Greg avait jeté l'opprobre sur nous, mais il avait prouvé que la revue de code était une façon intelligente de dépenser son temps, et que chacun pouvait contribuer autant au projet en analysant le code des autres qu'en écrivant du code soi-même. Une fois qu'il l'eu démontré, ceci devint le comportement par défaut, au point qu'un commit sans réaction aurait causé de l'angoisse à son émetteur, et qu'il aurait demandé sur la liste si quelqu'un avait déjà pu faire la revue. Plus tard, Greg trouva un travail qui ne lui laissait peu de temps pour Subversion, et du arrêter ses revues régulières, mais cette coutume était si bien enracinée en nous tous qu'elle est toujours activement pratiquée depuis un temps immémorial.

Commencez à faire des revues depuis le premier commit. Les types de problèmes les plus faciles à détecter de cette façon sont les vulnérabilités de sécurité, les fuites mémoire, les manques de commentaires ou de documentation d'API, les effets de bord, les erreurs de conception dans la hiérarchie d'appels, et d'autres problèmes qui nécessitent un minimum de recul pour être détectés. Néanmoins, même les problèmes à plus grande échelle comme l'incapacité à mutualiser du code à un seul endroit devient visible à force de revues, parce que le souvenir des revues précédentes renseigne les revues courantes.

Ne vous inquiétez pas si vous ne trouver rien à commenter, ou si vous de maîtrisez pas assez toutes les parties du code. Il y aura souvent quelque chose à dire sur tout commit ; même si vous ne trouvez rien à redire, quelque chose peut faire l'objet d'un commentaire admiratif. L'important est de rendre clair le fait que chaque développeur sache que ce qu'il fait est vu et compris. Bien entendu, la revue du code n'absout pas les programmeurs de leur responsabilité à vérifier et à tester leurs modifications avant de commiter; personne ne devrait dépendre de la revue pour détecter des problèmes qu'on aurait dû trouver soit-même.

Si vous libérez un projet existant, sur lequel travaillent des développeurs actifs et accoutumés à travailler dans un environnement propriétaire, assurez vous que tous comprennent qu'un changement important va en suivre, et de votre coté, vérifiez que vous êtes en mesure de faire face leurs réactions.

Représentez vous la situation telle qu'ils la perçoivent : tout le code et les décisions sur la conception sont faites par un groupe de développeurs qui connaissent tous plus ou moins autant le logiciel, qui reçoivent la même pression du même management, et qui connaissent leurs forces et faiblesses respectives. Vous leur demandez soudain d'exposer leur code pour qu'il soit scruté par des étrangers ne formant leur jugement que sur le résultat final, et sans prendre en compte la pression de la hiérarchie qui a pu forcer certaines décisions. Ces étrangers posent de nombreuses questions, des questions qui déstabilisent les développeurs lorsqu'ils réalisent que la documentation sur laquelle il avait tant travaillé est toujours inadéquate (c'est inévitable). Ajoutez le fait que tous ces arrivants sont inconnus et sans visage... Si l'un des développeurs manquait d'assurance, imaginez à quel point ce sentiment se trouvera exacerbé quand des nouveaux contributeurs lui désigneront des faiblesses dans son code, et pire, devant ses collègues. A moins de disposer d'une équipe de développeurs parfaits, c'est inévitable, en fait cela se produira probablement pour tous. Non pas qu'ils soient de mauvais programmeurs, c'est simplement qu'au dessus d'une certaine taille un projet a des bogues et la revue par pairs permettra de les détecter (voir la section intitulée « Pratiquez la revue par pairs » précédemment dans ce chapitre). Dans le même temps, les nouveaux arrivants ne seront pas eux mêmes sujets à la revue par pairs puisqu'ils ne peuvent produire de code tant qu'ils ne sont pas suffisamment familiers du projet. Pour vos développeurs, cela peut être pris comme une situation de critique unilatérale. Il y a donc danger de voir apparaître une mentalité d'assiégés parmi les vétérans.

La meilleure façon de l'éviter est de prévenir le groupe de ce qui va arriver. Expliquer lui que l'inconfort initial est parfaitement normal, et rassurez en assurant que les choses iront en s'améliorant. Certains de ces messages peuvent rester privés, avant que le projet ne soit ouvert. Mais vous pouvez également trouver utile d'informer sur la liste publique qu'une nouvelle méthode de développement pour le projet se met en place, et qu'un temps d'adaptation sera nécessaire. La meilleur chose que vous puissiez faire est de piloter par l'exemple. Si vous constatez que vos développeurs ne répondent pas suffisamment aux questions des débutants, leur demander simplement d'y répondre plus ne fera pas avancer les choses. Ils peuvent manquer de discernement entre ce qui nécessite une réponse ou pas, ou ne pas savoir comment prioriser le travail de développement face à la nouvelle charge amenée par cette communication externe. Le moyen de les faire participer est de participer vous mêmes. Soyez sur la mailing liste publique, et répondez y à des questions. Si vous n'avez pas l'expertise pour répondre à une question, désignez clairement un développeur qui la possède, et vérifiez qu'il fournira une solution ou au moins une réponse. Il peut être naturellement tentant sur le long terme de glisser vers des discussion privées, ce qui constituait après tout la situation antérieure. Assurez vous de vous inscrire sur les mailing listes internes sur lesquelles cela peut se produire pour être en mesure de demander à déplacer ces discussions vers la mailing liste publique.

Il existe d'autres considérations de long terme à prendre en compte lorsqu'on ouvre un projet propriétaire. Chapitre 4, Social and Political Infrastructure explore les techniques de management permettant de faire travailler avec succès contributeurs bénévoles et salariés, et Chapitre 9, Licenses, Copyrights, and Patents discute de la nécessité d'un travail juridique consciencieux lorsqu'on ouvre une base de code privée qui peut contenir du code écrit ou "détenu" par d'autres tiers.

Entre le moment où j'écris cette phrase et le moment où elle sera publiée, le problème du spam sur Internet aura sûrement pris des proportions beaucoup plus importantes ou, en tout cas, on le ressentira comme tel. Il fut un temps, il n'y a pas si longtemps, où l'on pouvait créer une liste de diffusion sans avoir à prendre de mesures de protection contre le spam. De temps en temps, on pouvait recevoir un e-mail égaré, mais c'était suffisamment rare pour que cela reste peu gênant. Cette âge d'or est révolu. De nos jours, une liste de diffusion qui ne se prémunie pas du spam sera rapidement noyée sous les e-mails indésirables, au point qu'elle en devienne inutilisable. Les protections contre le spam sont indispensables.

On peut séparer les protections contre le spam en deux catégories : celles qui empêchent les courriers indésirables d'apparaître sur la liste de diffusion et celles qui protègent les listes de diffusions contre les collecteurs d'adresses des spammeurs. La première étant la plus importante, c'est celle que nous allons détailler en premier.

Les utilisateurs des listes rangeront souvent les messages dans des dossiers réservés au projet, séparés de leurs autres courriers. Leur logiciel de lecture de courrier peut faire cela automatiquement en vérifiant les en-têtes du message. Les en-têtes sont les champs au début du courrier qui indiquent l’expéditeur, le destinataire, le sujet, la date et d’autres informations à propos du message. Certains en-têtes sont bien connus et obligatoires :

De: ...
À: ...
Sujet: ...
Date: ...

D’autres sont optionnels bien que plutôt courants. Par exemple, vous n’êtes pas obligés de remplir l’en-tête :

Répondre à: expediteur@addresse.courriel.ici

Mais la plupart des gens le font puisque cela permet au destinataire de répondre de manière certaine à l’auteur du message (c’est particulièrement utile si l’auteur a dû recourir à une adresse différente de celle à laquelle les réponses devraient être adressées).

Certains logiciels de courrier fournissent une interface simple d’emploi pour trier les messages en fonction du sujet. Certaines personnes demandent par conséquent que les listes de diffusion ajoutent automatiquement un préfixe aux sujets afin que leur logiciel puisse automatiquement ranger ces messages dans le bon dossier. L’idée est que l’auteur du message écrive :

Sujet: Préparation de la version 2.5

mais que le message au final soit envoyé sous cette forme (par exemple) :

Sujet: [discussion@listes.exemple.org] Préparation de la version 2.5

Bien que la plupart des logiciels de gestion de listes de diffusion proposent cette option, je ne vous recommande pas de l’activer. Le problème réglé ici peut l’être par des moyens beaucoup moins marqués, et le prix à payer, l’utilisation de l’espace dans le champ Sujet, est bien trop élevé. Les utilisateurs habitués aux listes de diffusion passent en général en revue les sujets des messages pour décider de ce qu’ils vont lire et ce à quoi ils vont répondre. Ajouter le nom de la liste au sujet peut repousser la partie importante du sujet hors de l’écran, la rendant ainsi invisible. Cela masque les informations sur lesquelles les gens se reposent durant leur inspection des sujets, réduisant par conséquent l’utilité de la liste de diffusion.

Plutôt que de grignoter une partie du champ Sujet, enseignez aux utilisateurs à utiliser les autres champs, en commençant par le champ À : qui devrait afficher le nom de la liste :

À: <discussion@listes.exemple.org>

N’importe quel logiciel de messagerie pouvant filtrer les sujets devrait également pouvoir filtrer aussi facilement le champ À :.

D’autres champs optionnels sont en général remplis pour les listes de diffusion. Baser le filtrage sur ces champs est encore plus efficace que d’utiliser les champs À : ou Cc : puisque ces champs sont remplis automatiquement par le logiciel de la liste de diffusion, certains utilisateurs s’attendent à les trouver :

list-help: <mailto:discuss-help@lists.example.org>
list-unsubscribe: <mailto:discuss-unsubscribe@lists.example.org>
list-post: <mailto:discuss@lists.example.org>
Delivered-To: mailing list discuss@lists.example.org
Mailing-List: contact discuss-help@lists.example.org; run by ezmlm

Pour la plupart, leur fonction est évidente. Voyez http://www.nisto.com/listspec/list-manager-intro.html plus d’informations à ce sujet ou, si vous cherchez des spécifications vraiment détaillées et formelles, voyez http://www.faqs.org/rfcs/rfc2369.html.

Vous remarquerez que ces champs suggèrent que si vous avez une liste nommée "list", alors vous possédez aussi les listes administratives "list-help" et "list-unsubscribe". En plus de celles-ci, il est normal que vous proposiez "list-subscribe" pour s’inscrire et "list-owner" pour contacter les administrateurs des listes. En fonction du logiciel utilisé pour gérer vos listes, ces adresses et/ou plusieurs autres adresses administratives peuvent être mises en place, vous trouverez des explications dans la documentation. En général, un descriptif complet de toutes ces adresses spéciales est communiqué à chaque nouvel utilisateur au sein d’un message de bienvenue lors de l’inscription. Vous recevrez aussi certainement une copie de ce courrier. Si vous ne la recevez pas, alors demandez ce que reçoivent les utilisateurs lorsqu’ils s’inscrivent à une liste. Gardez ce message à portée afin de pouvoir répondre aux questions concernant les fonctions de la liste de diffusion ou, encore mieux, affichez-le sur une page Web, ainsi quand quelqu’un perd sa copie des instructions et envoie un message concernant les modalités de désinscription, vous n’avez qu’à lui envoyer l’URL.

Certains logiciels de liste de diffusion possèdent une option pour ajouter les instructions de désabonnement à chaque message. Si cette option est présente, activez-la. Cela n’ajoute que quelques lignes au message, ne gêne pas sa lecture, et peut vous faire gagner beaucoup de temps en évitant que les gens ne vous écrivent, ou pire encore, n’écrivent à toute la liste, pour demander comment se désinscrire.

Précédemment, dans une partie appelée la section intitulée « Évitez les discussions privées », j’ai insisté sur l’importance du fait que les discussions doivent se dérouler dans les forums publics, et j’ai dit que parfois des mesures devaient être prises pour éviter que les conversations ne se transforment en échanges d’e-mails privés. Ce chapitre traite de la mise en place des logiciels de communication du projet afin qu’ils facilitent au maximum la vie du projet. Par conséquent, si le logiciel de gestion des listes de discussion vous offre la possibilité de garder automatiquement les discussions sur la liste, vous vous direz qu’il est logique d’activer cette fonctionnalité.

En fait ce n’est pas si évident. Cette option existe, mais elle comporte des inconvénients plutôt restrictifs. Son utilisation est sujette à l’un des plus importants débats concernant la gestion des listes de diffusion, rien qui ne fera la une des journaux du soir, mais parfois les discussions à ce propos peuvent devenir tendues au sein des projets de logiciels libres. Ci-dessous je vais décrire la fonctionnalité, exposer les principaux arguments de chaque camp et vous donner mes meilleures recommandations.

La fonctionnalité en elle-même est très simple : le logiciel peut, si vous le souhaitez, remplir le champ Répondre à : automatiquement afin que les réponses soient redirigées sur la liste de diffusion. C’est à dire que, peu importe ce que l’expéditeur met dans le champ Répondre à : (ou même s’il ne le remplit pas), quand les abonnés de la liste recevront le message l’en-tête contiendra l’adresse de la liste :

Répondre à: discuss@lists.example.org

De prime abord, cela semble être une bonne chose parce que quasiment tous les logiciels de messagerie inspectent le champ Répondre à : et donc quand quelqu’un enverra une réponse, elle sera automatiquement envoyée à la liste entière : pas uniquement à l’expéditeur du message auquel on répond. Bien sûr, la personne qui répond peut modifier à la main le destinataire du message, mais l’important est que, par défaut, les réponses sont directement envoyées à la liste. C’est un très bon exemple d’utilisation de la technologie pour encourager la collaboration.

Malheureusement, il existe quelques inconvénients. Le premier est connu sous le nom du problème de Je ne peux plus retrouver mon chemin : il se peut que l’expéditeur mette sa « véritable » adresse e-mail dans le champ Répondre à : parce que, pour une raison ou pour une autre, il a utilisé une autre adresse pour envoyer le message que celle qu’il utilise pour les recevoir. Les personnes qui expédient et lisent les messages à partir de la même adresse n’ont pas ce problème, et sont même parfois surprises d’apprendre son existence. Mais, pour ceux qui utilisent leurs comptes mail de manière particulière ou qui n’ont pas de contrôle sur le champ De : dans leurs courriers (parce qu’ils écrivent depuis leur travail, ou parce qu’ils n’ont pas assez d’influence sur le département informatique), utiliser le champ Répondre à : peut être la seule manière d’être sûr que les réponses leur parviennent. Quand une personne dans cette situation envoie un message à une liste de diffusion à laquelle il n’est pas abonné, l’adresse dans le champ Répondre à : devient une information essentielle. Si le logiciel remplace cette adresse, il se peut qu’il ne reçoive jamais de réponse.

Le deuxième inconvénient est lié aux attentes et, d’après moi, c’est l’argument qui a le plus de poids contre l’automatisation du champ Répondre à :. La majorité des gens ayant l’habitude de se servir des e-mails sont accoutumés à deux choix simples pour répondre : Répondre à tous et Répondre. Tous les logiciels modernes de messagerie possèdent deux boutons distincts pour ces deux fonctions. Les utilisateurs savent que pour répondre à tout le monde (ce qui inclut la liste), ils doivent utiliser le bouton « Répondre à tous », et que pour répondre en privé à l’auteur ils doivent utiliser le bouton « Répondre ». Même si votre but est d’encourager les gens à répondre à toute la liste le plus souvent possible, il y aura parfois des circonstances qui font qu’une réponse privée est plus appropriée, par exemple, si une personne veut dire quelque chose de confidentiel à l’auteur du message original, quelque chose qui n’aurait pas sa place sur la liste publique.

Maintenant penchons-nous sur le cas où la liste a ré-écrit le champ Répondre à :. La personne qui répond appuie sur le bouton « Répondre » en s’attendant à envoyer un message privé à l’auteur du courrier. Puisque c’est ce qu’il se passe normalement, il ne prendra pas forcément la peine de vérifier l’adresse du destinataire du message. Il écrit alors son message privé et confidentiel, où il pourrait dire des choses gênantes sur une autre personne de la liste, et appuie ensuite sur « Envoi ». Alors qu’il ne s’y attendait pas, quelques minutes plus tard son message apparaît sur la liste de diffusion ! Il aurait effectivement, en théorie, dû prendre le temps de regarder avec précaution le champ Destinataire, et n’aurait pas dû supposer qu’il n’avait pas à se soucier du champ Répondre à :. Mais les expéditeurs règlent quasiment à chaque fois le champ Répondre à : de telle sorte qu’ils reçoivent la réponse (ou pour être plus précis, c’est leur logiciel de messagerie qui le fait pour eux), et beaucoup d’utilisateurs expérimentés le prennent pour argent comptant. En fait, lorsqu’une personne met une autre adresse que celle de l’expéditeur dans le champ Répondre à :, comme celle de la liste par exemple, il prendra en général la peine de le notifier dans le message, ainsi les gens ne seront pas surpris par ce qui se passe lorsqu’ils appuient sur « Répondre ».

À cause des lourdes conséquences potentielles que cela peut entraîner, je préfère configurer le logiciel de gestion de liste de manière à ce qu’il ne modifie pas le champ Répondre à :. C’est l’un des cas où l’utilisation de la technologie pour encourager la collaboration peut, à mon sens, avoir des effets pervers. Mais l’autre camp a également d’excellents arguments à faire valoir. Quel que soit votre choix, des gens de temps à autre vous demanderont pourquoi vous n’avez pas fait l’autre choix. Comme c’est quelque chose que vous ne voulez pas voir prendre de trop grandes proportions, il vaut mieux que vous ayez une réponse toute prête, une réponse qui mettra un terme au débat plutôt que de l’encourager. Ne faites pas paraître votre décision, que vous choisissiez une solution ou l’autre, comme étant la seule, l’unique valable et la bonne (même si vous pensez que c’est le cas). Insistez plutôt sur le fait que c’est un très vieux débat, que les deux camps possèdent de bon arguments, mais qu’aucun choix ne peut satisfaire tous les utilisateurs, en conséquence, vous avez pris la décision qui vous semblait la meilleure. Demandez poliment à ce que le sujet ne soit pas ré-ouvert, à moins que quelqu’un ait quelque chose de vraiment nouveau à apporter au débat, puis ne participez plus à la discussion en espérant qu’elle s’éteigne d’elle-même.

Quelqu’un pourrait suggérer de voter pour choisir une méthode ou l’autre. Vous pouvez le faire si c’est votre choix, mais je ne pense pas qu’un vote à main levée soit la meilleure solution dans ce cas. Le risque que quelqu’un se fasse surprendre par la modification du champ Répondre à : est trop important et le désagrément pour chacun est plutôt faible (devoir rappeler occasionnellement aux gens de répondre à la liste entière) pour qu’une majorité, même si c’est la majorité, impose un tel risque à une minorité.

Je n’ai pas abordé, ici, tous les aspects de ce problème, seulement ceux qui semblaient les plus importants. Si le sujet vous intéresse je vous conseille de lire ces deux documents canoniques toujours cités dans ce débat :

Malgré cette légère préférence énoncée ci-dessus, je ne pense pas qu’il existe une vérité « transcendante » à sujet, et je participe gaiement à de nombreuses listes imposant le Répondre à :. Le mieux que vous puissiez faire, est d’opter assez tôt pour une solution ou pour l’autre, et d’éviter de vous faire attirer dans un débat par la suite.

Les détails techniques concernant la mise en place de l’archivage d’une liste de diffusion sont particuliers au logiciel qui fait fonctionner la liste et dépassent le cadre de ce livre. Lors du choix, ou de la configuration, de l’archive, vous devez prendre en compte les facteurs suivants :

Ceci n’est qu’une liste technique pour vous aider à évaluer et mettre en place un outil d’archivage. Comment amener les gens à vraiment utiliser cet outil pour le bien du projet, est un sujet différent, qui sera abordé dans d’autres chapitres de cet ouvrage, en particulier dans la section intitulée la section intitulée « Conspicuous Use of Archives ».

Voici une liste d’outils Open Source pour la gestion et l’archivage de listes. Si le site qui héberge votre projet propose déjà une configuration par défaut, vous n’aurez peut-être jamais à faire de choix. Mais si vous devez en installer un vous-même, en voici quelques-uns. Ceux que j’ai utilisés sont Mailman, Ezmlm, MHonArc et Hyper- mail, mais cela ne veut pas dire que les autres ne sont pas bons (et bien sûr, il en existe probablement sur lesquels je ne suis pas tombé ; cette liste n’est en rien exhaustive).

Les logiciels de gestion de listes de diffusion sont :

Les logiciels d’archivage sont :

Ce livre ne vous enseignera pas l’emploi de la gestion de versions si vous ne l’avez pas déjà expérimenté auparavant, cependant il serait impossible d’aborder ce sujet sans quelques termes clés. Ces termes sont utiles, indépendamment de tout système de gestion de versions : ce sont les noms et verbes de base de la collaboration en réseau, et ils seront employés de manière générique tout au long de ce livre. Même s’il n’existait aucun système de gestion de versions, le problème de gestion des modifications serait quand même présent, et ces mots nous fournissent un langage pour en parler de manière concise.

As of this writing, the two most popular version control systems in the free software world are Concurrent Versions System (CVS, http://www.cvshome.org/) and Subversion (SVN, http://subversion.tigris.org/).

CVS has been around for a long time. Most experienced developers are already familiar with it, it does more or less what you need, and since it's been popular for a long time, you probably won't end up in any long debates about whether or not it was the right choice. CVS has some disadvantages, however. It doesn't provide an easy way to refer to multi-file changes; it doesn't allow you to rename or copy files under version control (so if you need to reorganize your code tree after starting the project, it can be a real pain); it has poor merging support; it doesn't handle large files or binary files very well; and some operations are slow when large numbers of files are involved.

None of CVS's flaws is fatal, and it is still quite popular. However, in the last few years the more recent Subversion has been gaining ground, especially in newer projects.^[14]. If you're starting a new project, I recommend Subversion.

On the other hand, since I'm involved in the Subversion project, my objectivity might reasonably by questioned. And in the last few years a number of new open-source version control systems have appeared. Annexe A, Free Version Control Systems lists all the ones I know of, in rough order of popularity. As the list makes clear, deciding on a version control system could easily become a lifelong research project. Possibly you will be spared the decision because it will be made for you by your hosting site. But if you must choose, consult with your other developers, ask around to see what people have experience with, then pick one and run with it. Any stable, production-ready version control system will do; you don't have to worry too much about making a drastically wrong decision. If you simply can't make up your mind, then go with Subversion. It's fairly easy to learn, and is likely to remain a standard for at least a few years.

The recommendations in this section are not targeted toward a particular version control system, and should be simple to implement in any of them. Consult your specific system's documentation for details.

Make sure the bug tracker doesn't turn into a discussion forum. Although it is important to maintain a human presence in the bug tracker, it is not fundamentally suited to real-time discussion. Think of it rather as an archiver, a way to organize facts and references to other discussions, primarily those that take place on mailing lists.

There are two reasons to make this distinction. First, the bug tracker is more cumbersome to use than the mailing lists (or than real-time chat forums, for that matter). This is not because bug trackers have bad user interface design, it's just that their interfaces were designed for capturing and presenting discrete states, not free-flowing discussions. Second, not everyone who should be involved in discussing a given issue is necessarily watching the bug tracker. Part of good issue management (see la section intitulée « Share Management Tasks as Well as Technical Tasks » in Chapitre 8, Managing Volunteers) is to make sure each issue is brought to the right peoples' attention, rather than requiring every developer to monitor all issues. In la section intitulée « No Conversations in the Bug Tracker » in Chapitre 6, Communications, we'll look at ways to make sure people don't accidentally siphon discussions out of appropriate forums and into the bug tracker.

Some bug trackers can monitor mailing lists and automatically log all emails that are about a known issue. Typically they do this by recognizing the issue's identifying number in the subject line of the mail, as part of a special string; developers learn to include these strings in their mails to attract the tracker's notice. The bug tracker may either save the entire email, or (even better) just record a link to the mail in the regular mailing list archive. Either way, this is a very useful feature; if your tracker has it, make sure both to turn it on and to remind people to take advantage of it.

Most issue databases eventually suffer from the same problem: a crushing load of duplicate or invalid issues filed by well-meaning but inexperienced or ill-informed users. The first step in combatting this trend is usually to put a prominent notice on the front page of the bug tracker, explaining how to tell if a bug is really a bug, how to search to see if it's already been filed, and finally, how to effectively report it if one still thinks it's a new bug.

This will reduce the noise level for a while, but as the number of users increases, the problem will eventually come back. No individual user can be blamed for it. Each one is just trying to contribute to the project's well-being, and even if their first bug report isn't helpful, you still want to encourage them to stay involved and file better issues in the future. In the meantime, though, the project needs to keep the issue database as free of junk as possible.

The two things that will do the most to prevent this problem are: making sure there are people watching the bug tracker who have enough knowledge to close issues as invalid or duplicates the moment they come in, and requiring (or strongly encouraging) users to confirm their bugs with other people before filing them in the tracker.

The first technique seems to be used universally. Even projects with huge issue databases (say, the Debian bug tracker at http://bugs.debian.org/, which contained 315,929 issues as of this writing) still arrange things so that someone sees each issue that comes in. It may be a different person depending on the category of the issue. For example, the Debian project is a collection of software packages, so Debian automatically routes each issue to the appropriate package maintainers. Of course, users can sometimes misidentify an issue's category, with the result that the issue is sent to the wrong person initially, who may then have to reroute it. However, the important thing is that the burden is still shared—whether the user guesses right or wrong when filing, issue watching is still distributed more or less evenly among the developers, so each issue is able to receive a timely response.

The second technique is less widespread, probably because it's harder to automate. The essential idea is that every new issue gets "buddied" into the database. When a user thinks he's found a problem, he is asked to describe it on one of the mailing lists, or in an IRC channel, and get confirmation from someone that it is indeed a bug. Bringing in that second pair of eyes early can prevent a lot of spurious reports. Sometimes the second party is able to identify that the behavior is not a bug, or is fixed in recent releases. Or she may be familiar with the symptoms from a previous issue, and can prevent a duplicate filing by pointing the user to the older issue. Often it's enough just to ask the user "Did you search the bug tracker to see if it's already been reported?" Many people simply don't think of that, yet are happy to do the search once they know someone's expecting them to.

The buddy system can really keep the issue database clean, but it has some disadvantages too. Many people will file solo anyway, either through not seeing, or through disregarding, the instructions to find a buddy for new issues. Thus it is still necessary for volunteers to watch the issue database. Furthermore, because most new reporters don't understand how difficult the task of maintaining the issue database is, it's not fair to chide them too harshly for ignoring the guidelines. Thus the volunteers must be vigilant, and yet exercise restraint in how they bounce unbuddied issues back to their reporters. The goal is to train each reporter to use the buddying system in the future, so that there is an ever-growing pool of people who understand the issue-filtering system. On seeing an unbuddied issue, the ideal steps are:

Remember that although this system will improve the signal/noise ratio in the issue database over time, it will never completely stop the misfilings. The only way to prevent misfilings entirely is to close off the bug tracker to everyone but developers—a cure that is almost always worse than the disease. It's better to accept that cleaning out invalid issues will always be part of the project's routine maintenance, and to try to get as many people as possible to help.

See also la section intitulée « Issue Manager » in Chapitre 8, Managing Volunteers.

Many technically-oriented IRC channels have a non-human member, a so-called bot, that is capable of storing and regurgitating information in response to specific commands. Typically, the bot is addressed just like any other member of the channel, that is, the commands are delivered by "speaking to" the bot. For example:

<kfogel> ayita: learn diff-cmd = http://subversion.tigris.org/faq.html#diff-cmd
<ayita>  Thanks!

That told the bot (who is logged into the channel as ayita) to remember a certain URL as the answer to the query "diff-cmd". Now we can address ayita, asking the bot to tell another user about diff-cmd:

<kfogel> ayita: tell jrandom about diff-cmd
<ayita>  jrandom: http://subversion.tigris.org/faq.html#diff-cmd

The same thing can be accomplished via a convenient shorthand:

<kfogel> !a jrandom diff-cmd
<ayita>  jrandom: http://subversion.tigris.org/faq.html#diff-cmd

The exact command set and behaviors differ from bot to bot. The above example is with ayita (http://hix.nu/svn-public/alexis/trunk/), of which there is usually an instance running in #svn at freenode. Other bots include Dancer (http://dancer.sourceforge.net/) and Supybot (http://supybot.com/). Note that no special server privileges are required to run a bot. A bot is a client program; anyone can set one up and direct it to listen to a particular server/channel.

If your channel tends to get the same questions over and over, I highly recommend setting up a bot. Only a small percentage of channel users will acquire the expertise needed to manipulate the bot, but those users will answer a disproportionately high percentage of questions, because the bot enables them to respond so much more efficiently.

Although it is possible to archive everything that happens in an IRC channel, it's not necessarily expected. IRC conversations may be nominally public, but many people think of them as informal, semi-private conversations. Users may be careless with grammar, and often express opinions (for example, about other software or other programmers) that they wouldn't want preserved forever in an online archive.

Of course, there will sometimes be excerpts that should be preserved, and that's fine. Most IRC clients can log a conversation to a file at the user's request, or failing that, one can always just cut and paste the conversation from IRC into a more permanent forum (most often the bug tracker). But indiscriminate logging may make some users uneasy. If you do archive everything, make sure you state so clearly in the channel topic, and give a URL to the archive.

There are two main advantages to using a canned site. The first is server capacity and bandwidth: their servers are beefy boxes sitting on really fat pipes. No matter how successful your project gets, you're not going to run out of disk space or swamp the network connection. The second advantage is simplicity. They have already chosen a bug tracker, a version control system, a mailing list manager, an archiver, and everything else you need to run a site. They've configured the tools, and are taking care of backups for all the data stored in the tools. You don't need to make many decisions. All you have to do is fill in a form, press a button, and suddenly you've got a project web site.

These are pretty significant benefits. The disadvantage, of course, is that you must accept their choices and configurations, even if something different would be better for your project. Usually canned sites are adjustable within certain narrow parameters, but you will never get the fine-grained control you would have if you set up the site yourself and had full administrative access to the server.

A perfect example of this is the handling of generated files. Certain project web pages may be generated files—for example, there are systems for keeping FAQ data in an easy-to-edit master format, from which HTML, PDF, and other presentation formats can be generated. As explained in la section intitulée « Version everything » earlier in this chapter, you wouldn't want to version the generated formats, only the master file. But when your web site is hosted on someone else's server, it may be impossible to set up a custom hook to regenerate the online HTML version of the FAQ whenever the master file is changed. The only workaround is to version the generated formats too, so that they show up on the web site.

There can be larger consequences as well. You may not have as much control over presentation as you would wish. Some of the canned hosting sites allow you to customize your web pages, but the site's default layout usually ends up showing through in various awkward ways. For example, some projects that host themselves at SourceForge have completely customized home pages, but still point developers to their "SourceForge page" for more information. The SourceForge page is what would be the project's home page, had the project not used a custom home page. The SourceForge page has links to the bug tracker, the CVS repository, downloads, etc. Unfortunately, a SourceForge page also contains a great deal of extraneous noise. The top is a banner ad, often an animated image. The left side is a vertical arrangement of links of little relevance to someone interested in the project. The right side is often another advertisement. Only the center of the page is devoted to truly project-specific material, and even that is arranged in a confusing way that often makes visitors unsure of what to click on next.

Behind every individual aspect of SourceForge's design, there is no doubt a good reason—good from SourceForge's point of view, such as the advertisements. But from an individual project's point of view, the result can be a less-than-ideal web page. I don't mean to pick on SourceForge; similar concerns apply to many of the canned hosting sites. The point is that there's a tradeoff. You get relief from the technical burdens of running a project site, but only at the price of accepting someone else's way of running it.

Only you can decide whether canned hosting is best for your project. If you choose a canned site, leave open the option of switching to your own servers later, by using a custom domain name for the project's "home address". You can forward the URL to the canned site, or have a fully customized home page at the public URL and hand users off to the canned site for sophisticated functionality. Just make sure to arrange things such that if you later decide to use a different hosting solution, the project's address doesn't need to change.

Being a BD requires a combination of traits. It needs, first of all, a well-honed sensitivity to one's own influence in the project, which in turn brings self-restraint. In the early stages of a discussion, one should not express opinions and conclusions with so much certainty that others feel like it's pointless to dissent. People must be free to air ideas, even stupid ideas. It is inevitable that the BD will post a stupid idea from time to time too, of course, and therefore the role also requires an ability to recognize and acknowledge when one has made a bad decision—though this is simply a trait that any good developer should have, especially if she stays with the project a long time. But the difference is that the BD can afford to slip from time to time without worrying about long-term damage to her credibility. Developers with less seniority may not feel so secure, so the BD should phrase critiques or contrary decisions with some sensitivity for how much weight her words carry, both technically and psychologically.

The BD does not need to have the sharpest technical skills of anyone in the project. She must be skilled enough to work on the code herself, and to understand and comment on any change under consideration, but that's all. The BD position is neither acquired nor held by virtue of intimidating coding skills. What is important is experience and overall design sense—not necessarily the ability to produce good design on demand, but the ability to recognize good design, whatever its source.

It is common for the benevolent dictator to be a founder of the project, but this is more a correlation than a cause. The sorts of qualities that make one able to successfully start a project—technical competence, ability to persuade other people to join, etc.—are exactly the qualities any BD would need. And of course, founders start out with a sort of automatic seniority, which can often be enough to make benevolent dictatorship appear the path of least resistance for all concerned.

Remember that the potential to fork goes both ways. A BD can fork a project just as easily as anyone else, and some have occasionally done so, when they felt that the direction they wanted to take the project was different from where the majority of other developers wanted to go. Because of forkability, it does not matter whether the benevolent dictator has root (system administrator privileges) on the project's main servers or not. People sometimes talk of server control as though it were the ultimate source of power in a project, but in fact it is irrelevant. The ability to add or remove people's commit passwords on one particular server affects only the copy of the project that resides on that server. Prolonged abuse of that power, whether by the BD or someone else, would simply lead to development moving to a different server.

The fact that the project's source code is kept under version control means that most decisions can be easily unmade. The most common way this happens is that someone commits a change mistakenly thinking everyone would be happy with it, only to be met with objections after the fact. It is typical for such objections to start out with an obligatory apology for having missed out on prior discussion, though this may be omitted if the objector finds no record of such a discussion in the mailing list archives. Either way, there is no reason for the tone of the discussion to be different after the change has been committed than before. Any change can be reverted, at least until dependent changes are introduced (i.e., new code that would break if the original change were suddenly removed). The version control system gives the project a way to undo the effects of bad or hasty judgement. This, in turn, frees people to trust their instincts about how much feedback is necessary before doing something.

This also means that the process of establishing consensus need not be very formal. Most projects handle it by feel. Minor changes can go in with no discussion, or with minimal discussion followed by a few nods of agreement. For more significant changes, especially ones with the potential to destabilize a lot of code, people should wait a day or two before assuming there is consensus, the rationale being that no one should be marginalized in an important conversation simply because he didn't check email frequently enough.

Thus, when someone is confident he knows what needs to be done, he should just go ahead and do it. This applies not only to software fixes, but to web site updates, documentation changes, and anything else unlikely to be controversial. Usually there will be only a few instances where an action needs to be undone, and these can be handled on a case-by-case basis. Of course, one shouldn't encourage people to be headstrong. There is still a psychological difference between a decision under discussion and one that has already taken effect, even if it is technically reversible. People always feel that momentum is allied to action, and will be slightly more reluctant to revert a change than to prevent it in the first place. If a developer abuses this fact by committing potentially controversial changes too quickly, however, people can and should complain, and hold that developer to a stricter standard until things improve.

Inevitably, some debates just won't consense. When all other means of breaking a deadlock fail, the solution is to vote. But before a vote can be taken, there must be a clear set of choices on the ballot. Here, again, the normal process of technical discussion blends serendipitously with the project's decision-making procedures. The kinds of questions that come to a vote often involve complex, multifaceted issues. In any such complex discussion, there are usually one or two people playing the role of honest broker: posting periodic summaries of the various arguments and keeping track of where the core points of disagreement (and agreement) lie. These summaries help everyone measure how much progress has been made, and remind everyone of what issues remain to be addressed. Those same summaries can serve as prototypes for a ballot sheet, should a vote become necessary. If the honest brokers have been doing their job well, they will be able to credibly call for a vote when the time comes, and the group will be willing to use a ballot sheet based on their summary of the issues. The brokers themselves may be participants in the debate; it is not necessary for them to remain above the fray, as long as they can understand and fairly represent others' views, and not let their partisan sentiments prevent them from summarizing the state of the debate in a neutral fashion.

The actual content of the ballot is usually not controversial. By the time matters reach a vote, the disagreement has usually boiled down to a few key issues, with recognizable labels and brief descriptions. Occasionally a developer will object to the form of the ballot itself. Sometimes his concern is legitimate, for example, that an important choice was left off or not described accurately. But other times a developer may be merely trying to stave off the inevitable, perhaps knowing that the vote probably won't go his way. See la section intitulée « Difficult People » in Chapitre 6, Communications for how to deal with this sort of obstructionism.

Remember to specify the voting system, as there are many different kinds, and people might make wrong assumptions about which procedure is being used. A good choice in most cases is approval voting, whereby each voter can vote for as many of the choices on the ballot as he likes. Approval voting is simple to explain and to count, and unlike some other methods, it only involves one round of voting. See http://en.wikipedia.org/wiki/Voting_system#List_of_systems for more details about approval voting and other voting systems, but try to avoid getting into a long debate about which voting system to use (because, of course, you will then find yourself in a debate about which voting system to use to decide the voting system!). One reason approval voting is a good choice is that it's very hard for anyone to object to—it's about as fair as a voting system can be.

Finally, conduct votes in public. There is no need for secrecy or anonymity in a vote on matters that have been debated publicly anyway. Have each participant post her votes to the project mailing list, so that any observer can tally and check the results for herself, and so that everything is recorded in the archives.

The hardest thing about voting is determining when to do it. In general, taking a vote should be very rare—a last resort for when all other options have failed. Don't think of voting as a great way to resolve debates. It isn't. It ends discussion, and thereby ends creative thinking about the problem. As long as discussion continues, there is the possibility that someone will come up with a new solution everyone likes. This happens surprisingly often: a lively debate can produce a new way of thinking about the problem, and lead to a proposal that eventually satisfies everyone. Even when no new proposal arises, it's still usually better to broker a compromise than to hold a vote. After a compromise, everyone is a little bit unhappy, whereas after a vote, some people are unhappy while others are happy. From a political standpoint, the former sitation is preferable: at least each person can feel he extracted a price for his unhappiness. He may be dissatisfied, but so is everyone else.

Voting's main advantage is that it finally settles a question so everyone can move on. But it settles it by a head count, instead of by rational dialogue leading everyone to the same conclusion. The more experienced people are with open source projects, the less eager I find them to be to settle questions by vote. Instead they will try to explore previously unconsidered solutions, or compromise more severely than they'd originally planned. Various techniques are available to prevent a premature vote. The most obvious is simply to say "I don't think we're ready for a vote yet," and explain why not. Another is to ask for an informal (non-binding) show of hands. If the response clearly tends toward one side or another, this will make some people suddenly more willing to compromise, obviating the need for a formal vote. But the most effective way is simply to offer a new solution, or a new viewpoint on an old suggestion, so that people re-engage with the issues instead of merely repeating the same arguments.

In certain rare cases, everyone may agree that all the compromise solutions are worse than any of the non-compromise ones. When that happens, voting is less objectionable, both because it is more likely to lead to a superior solution and because people will not be overly unhappy no matter how it turns out. Even then, the vote should not be rushed. The discussion leading up to a vote is what educates the electorate, so stopping that discussion early can lower the quality of the result.

(Note that this advice to be reluctant to call votes does not apply to the change-inclusion voting described in la section intitulée « Stabilizing a Release » in Chapitre 7, Packaging, Releasing, and Daily Development. There, voting is more of a communications mechanism, a means of registering one's involvement in the change review process so that everyone can tell how much review a given change has received.)

Having a voting system raises the question of electorate: who gets to vote? This has the potential to be a sensitive issue, because it forces the project to officially recognize some people as being more involved, or as having better judgement, than others.

The best solution is to simply take an existing distinction, commit access, and attach voting privileges to it. In projects that offer both full and partial commit access, the question of whether partial committers can vote largely depends on the process by which partial commit access is granted. If the project hands it out liberally, for example as a way of maintaining many third-party contributed tools in the repository, then it should be made clear that partial commit access is really just about committing, not voting. The reverse implication naturally holds as well: since full committers will have voting privileges, they must be chosen not only as programmers, but as members of the electorate. If someone shows disruptive or obstructionist tendencies on the mailing list, the group should be very cautious about making him a committer, even if the person is technically skilled.

The voting system itself should be used to choose new committers, both full and partial. But here is one of the rare instances where secrecy is appropriate. You can't have votes about potential committers posted to a public mailing list, because the candidate's feelings (and reputation) could be hurt. Instead, the usual way is that an existing committer posts to a private mailing list consisting only of the other committers, proposing that someone be granted commit access. The other committers speak their minds freely, knowing the discussion is private. Often there will be no disagreement, and therefore no vote necessary. After waiting a few days to make sure every committer has had a chance to respond, the proposer mails the candidate and offers him commit access. If there is disagreement, discussion ensues as for any other question, possibly resulting in a vote. For this process to be open and frank, the mere fact that the discussion is taking place at all should be secret. If the person under consideration knew it was going on, and then were never offered commit access, he could conclude that he had lost the vote, and would likely feel hurt. Of course, if someone explicitly asks for commit access, then there is no choice but to consider the proposal and explicitly accept or reject him. If the latter, then it should be done as politely as possible, with a clear explanation: "We liked your patches, but haven't seen enough of them yet," or "We appreciate all your patches, but they required considerable adjustments before they could be applied, so we don't feel comfortable giving you commit access yet. We hope that this will change over time, though." Remember, what you're saying could come as a blow, depending on the person's level of confidence. Try to see it from their point of view as you write the mail.

Because adding a new committer is more consequential than most other one-time decisions, some projects have special requirements for the vote. For example, they may require that the proposal receive at least n positive votes and no negative votes, or that a supermajority vote in favor. The exact parameters are not important; the main idea is to get the group to be careful about adding new committers. Similar, or even stricter, special requirements can apply to votes to remove a committer, though hopefully that will never be necessary. See la section intitulée « Committers » in Chapitre 8, Managing Volunteers for more on the non-voting aspects of adding and removing committers.

For certain kinds of votes, it may be useful to expand the electorate. For example, if the developers simply can't figure out whether a given interface choice matches the way people actually use the software, one solution is to ask to all the subscribers of the project's mailing lists to vote. These are really polls rather than votes, but the developers may choose to treat the result as binding. As with any poll, be sure to make it clear to the participants that there's a write-in option: if someone thinks of a better option not offered in the poll questions, her response may turn out to be the most important result of the poll.

Some projects allow a special kind of vote known as a veto. A veto is a way for a developer to put a halt to a hasty or ill-considered change, at least long enough for everyone to discuss it more. Think of a veto as somewhere between a very strong objection and a filibuster. Its exact meaning varies from one project to another. Some projects make it very difficult to override a veto; others allow them to be overridden by regular majority vote, perhaps after an enforced delay for more discussion. Any veto should be accompanied by a thorough explanation; a veto without such an explanation should be considered invalid on arrival.

With vetoes comes the problem of veto abuse. Sometimes developers are too eager to raise the stakes by casting a veto, when really all that was called for was more discussion. You can prevent veto abuse by being very reluctant to use vetoes yourself, and by gently calling it out when someone else uses her veto too often. If necessary, you can also remind the group that vetoes are binding for only as long as the group agrees they are—after all, if a clear majority of developers wants X, then X is going to happen one way or another. Either the vetoing developer will back down, or the group will decide to weaken the meaning of a veto.

You may see people write "-1" to express a veto. This usage comes from the Apache Software Foundation, which has a highly structured voting and veto process, described at http://www.apache.org/foundation/voting.html. The Apache standards have spread to other projects, and you will see their conventions used to varying degrees in a lot of places in the open source world. Technically, "-1" does not always indicate a formal veto even according to the Apache standards, but informally it is usually taken to mean a veto, or at least a very strong objection.

Like votes, vetoes can apply retroactively. It's not okay to object to a veto on the grounds that the change in question has already been committed, or the action taken (unless it's something irrevocable, like putting out a press release). On the other hand, a veto that arrives weeks or months late isn't likely to be taken very seriously, nor should it be.

The community is still important to the success of contract work. Their involvement in the design and review process for sizeable changes cannot be an afterthought. It must be considered part of the work, and fully embraced by the contractor. Don't think of community scrutiny as an obstacle to be overcome—think of it as a free design board and QA department. It is a benefit to be aggressively pursued, not merely endured.

Obviously, when you're choosing a contractor, you want someone with the right technical skills and experience for the job. But it's also important to choose someone with a track record of constructive interaction with the other developers in the community. That way you're getting more than just a single person; you're getting an agent who will be able to draw on a network of expertise to make sure the work is done in a robust and maintainable way.

In proprietary software development, it is normal to have teams of people dedicated solely to quality assurance: bug hunting, performance and scalability testing, interface and documentation checking, etc. As a rule, these activities are not pursued as vigorously by the volunteer community on a free software project. This is partly because it's hard to get volunteer labor for unglamorous work like testing, partly because people tend to assume that having a large user community gives the project good testing coverage, and, in the case of performance and scalability testing, partly because volunteers often don't have access to the necessary hardware resources anyway.

The assumption that having many users is equivalent to having many testers is not entirely baseless. Certainly there's little point assigning testers for basic functionality in common environments: bugs there will quickly be found by users in the natural course of things. But because users are just trying to get work done, they do not consciously set out to explore uncharted edge cases in the program's functionality, and are likely to leave certain classes of bugs unfound. Furthermore, when they discover a bug with an easy workaround, they often silently implement the workaround without bothering to report the bug. Most insidiously, the usage patterns of your customers (the people who drive your interest in the software) may differ in statistically significant ways from the usage patterns of the Average User In The Street.

A professional testing team can uncover these sorts of bugs, and can do so as easily with free software as with proprietary software. The challenge is to convey the testing team's results back to the public in a useful form. In-house testing departments usually have their own way of reporting test results, involving company-specific jargon, or specialized knowledge about particular customers and their data sets. Such reports would be inappropriate for the public bug tracker, both because of their form and because of confidentiality concerns. Even if your company's internal bug tracking software were the same as that used by the public project, management might need to make company-specific comments and metadata changes to the issues (for example, to raise an issue's internal priority, or schedule its resolution for a particular customer). Usually such notes are confidential—sometimes they're not even shown to the customer. But even when they're not confidential, they're of no concern to the public project, and therefore the public should not be distracted with them.

Yet the core bug report itself is important to the public. In fact, a bug report from your testing department is in some ways more valuable than one received from users at large, since the testing department probes for things that other users won't. Given that you're unlikely to get that particular bug report from any other source, you definitely want to preserve it and make it available to the public project.

To do this, either the QA department can file issues directly in the public issue tracker, if they're comfortable with that, or an intermediary (usually one of the developers) can "translate" the testing department's internal reports into new issues in the public tracker. Translation simply means describing the bug in a way that makes no reference to customer-specific information (the reproduction recipe may use customer data, assuming the customer approves it, of course).

It is somewhat preferable to have the QA department filing issues in the public tracker directly. That gives the public a more direct appreciation of your company's involvement with the project: useful bug reports add to your organization's credibility just as any technical contribution would. It also gives developers a direct line of communication to the testing team. For example, if the internal QA team is monitoring the public issue tracker, a developer can commit a fix for a scalability bug (which the developer may not have the resources to test herself), and then add a note to the issue asking the QA team to see if the fix had the desired effect. Expect a bit of resistance from some of the developers; programmers have a tendency to regard QA as, at best, a necessary evil. The QA team can easily overcome this by finding significant bugs and filing comprehensible reports; on the other hand, if their reports are not at least as good as those coming from the regular user community, then there's no point having them interact directly with the development team.

Either way, once a public issue exists, the original internal issue should simply reference the public issue for technical content. Management and paid developers may continue to annotate the internal issue with company-specific comments as necessary, but use the public issue for information that should be available to everyone.

You should go into this process expecting extra overhead. Maintaining two issues for one bug is, naturally, more work than maintaining one issue. The benefit is that many more coders will see the report and be able to contribute to a solution.

Corporations, for-profit or nonprofit, are almost the only entities that ever pay attention to complex legal issues in free software. Individual developers often understand the nuances of various open source licenses, but they generally do not have the time or resources to follow copyright, trademark, and patent law in detail. If your company has a legal department, it can help a project by vetting the copyright status of the code, and helping developers understand possible patent and trademark issues. The exact forms this help could take are discussed in Chapitre 9, Licenses, Copyrights, and Patents. The main thing is to make sure that communications between the legal department and the development community, if they happen at all, happen with a mutual appreciation of the very different universes the parties are coming from. On occasion, these two groups talk past each other, each side assuming domain-specific knowledge that the other does not have. A good strategy is to have a liaison (usually a developer, or else a lawyer with technical expertise) stand in the middle and translate for as long as needed.

Documentation and usability are both famous weak spots in open source projects, although I think, at least in the case of documentation, that the difference between free and proprietary software is frequently exaggerated. Nevertheless, it is empirically true that much open source software lacks first-class documentation and usability research.

If your organization wants to help fill these gaps for a project, probably the best thing it can do is hire people who are not regular developers on the project, but who will be able to interact productively with the developers. Not hiring regular developers is good for two reasons: one, that way you don't take development time away from the project; two, those closest to the software are usually the wrong people to write documentation or investigate usability anyway, because they have trouble seeing the software from an outsider's point of view.

However, it will still be necessary for whoever works on these problems to communicate with the developers. Find people who are technical enough to talk to the coding team, but not so expert in the software that they can't empathize with regular users anymore.

A medium-level user is probably the right person to write good documentation. In fact, after the first edition of this book was published, I received the following email from an open source developer named Dirk Reiners:

One comment on Money::Documentation and Usability: when we had some 
money to spend and decided that a beginner's tutorial was the most 
critical piece that we needed we hired a medium-level user to write it. 
He had gone through the induction to the system recently enough to 
remember the problems, but he had gotten past them so he knew how to 
describe them. That allowed him to write something that needed only 
minor fixes by the core developers for the things that he hadn't gotten 
right, but still covering the 'obvious' stuff devs would have missed.

His case was even better, as it had been his job to introduce a bunch of 
other people (students) to the system, so he combined the experience of 
many people, which is something that was just a lucky occurrence and is 
probably hard to get in most cases.

For a project that's not using one of the free canned hosting sites (see la section intitulée « Canned Hosting » in Chapitre 3, L'infrastructure technique), providing a server and network connection—and most importantly, system administration help—can be of significant assistance. Even if this is all your organization does for the project, it can be a moderately effective way to obtain good public relations karma, though it will not bring any influence over the direction of the project.

You can probably expect a banner ad or an acknowledgment on the project's home page, thanking your company for providing hosting. If you set up the hosting so that the project's web address is under your company's domain name, then you will get some additional association just through the URL. This will cause most users to think of the software as having something to do with your company, even if you don't contribute to development at all. The problem is, the developers are aware of this associative tendency too, and may not be very comfortable with having the project in your domain unless you're contributing more resources than just bandwidth. After all, there are a lot of places to host these days. The community may eventually feel that the implied misallocation of credit is not worth the convenience brought by hosting, and take the project elsewhere. So if you want to provide hosting, do so—but either plan to get even more involved soon, or be circumspect about how much involvement you claim.

For the sake of keeping the volunteer developer community on your side, it is very important not to say anything that isn't demonstrably true. Audit all claims carefully before making them, and give the public the means to check your claims on their own. Independent fact checking is a major part of open source, and it applies to more than just the code.

Naturally no one would advise companies to make unverifiable claims anyway. But with open source activities, there is an unusually high quantity of people with the expertise to verify claims—people who are also likely to have high-bandwidth Internet access and the right social contacts to publicize their findings in a damaging way, should they choose to. When Global Megacorp Chemical Industries pollutes a stream, that's verifiable, but only by trained scientists, who can then be refuted by Global Megacorp's scientists, leaving the public scratching their heads and wondering what to think. On the other hand, your behavior in the open source world is not only visible and recorded; it is also easy for many people to check it independently, come to their own conclusions, and spread those conclusions by word of mouth. These communications networks are already in place; they are the essence of how open source operates, and they can be used to transmit any sort of information. Refutation is usually difficult, if not impossible, especially when what people are saying is true.

For example, it's okay to refer to your organization as having "founded project X" if you really did. But don't refer to yourself as the "makers of X" if most of the code was written by outsiders. Conversely, don't claim to have a deeply involved volunteer developer community if anyone can look at your repository and see that there are few or no code changes coming from outside your organization.

Not too long ago, I saw an announcement by a very well-known computer company, stating that they were releasing an important software package under an open source license. When the initial announcement came out, I took a look at their now-public version control repository and saw that it contained only three revisions. In other words, they had done an initial import of the source code, but hardly anything had happened since then. That in itself was not worrying—they'd just made the announcement, after all. There was no reason to expect a lot of development activity right away.

Some time later, they made another announcement. Here is what it said, with the name and release number replaced by pseudonyms:

Curious to know what the community had uncovered in "rigorous testing," I went back to the repository to look at its recent change history. The project was still on revision 3. Apparently, they hadn't found a single bug worth fixing before the release! Thinking that the results of the community testing must have been recorded elsewhere, I next examined the bug tracker. There were exactly six open issues, four of which had been open for several months already.

This beggars belief, of course. When testers pound on a large and complex piece of software for any length of time, they will find bugs. Even if the fixes for those bugs don't make it into the upcoming release, one would still expect some version control activity as a result of the testing process, or at least some new issues. Yet to all appearances, nothing had happened between the announcement of the open source license and the first open source release.

The point is not that the company was lying about the community testing. I have no idea if they were or not. But they were oblivious to how much it looked like they were lying. Since neither the version control repository nor the issue tracker gave any indication that the alleged rigorous testing had occurred, the company should either not have made the claim in the first place, or provided a clear link to some tangible result of that testing ("We found 278 bugs; click here for details"). The latter would have allowed anyone to get a handle on the level of community activity very quickly. As it was, it only took me a few minutes to determine that whatever this community testing was, it had not left traces in any of the usual places. That's not a lot of effort, and I'm sure I'm not the only one who took the trouble.

Transparency and verifiability are also an important part of accurate crediting, of course. See la section intitulée « Credit » in Chapitre 8, Managing Volunteers for more on this.

Refrain from giving negative opinions about competing open source software. It's perfectly okay to give negative facts—that is, easily confirmable assertions of the sort often seen in good comparison charts. But negative characterizations of a less rigorous nature are best avoided, for two reasons. First, they are liable to start flame wars that detract from productive discussion. Second, and more importantly, some of the volunteer developers in your project may turn out to work on the competing project as well. This is more likely than it at first might seem: the projects are already in the same domain (that's why they're in competition), and developers with expertise in that domain may make contributions wherever their expertise is applicable. Even when there is no direct developer overlap, it is likely that developers on your project are at least acquainted with developers on related projects. Their ability to maintain constructive personal ties could be hampered by overly negative marketing messages.

Bashing competing closed-source products seems to be more widely accepted in the open source world, especially when those products are made by Microsoft. Personally, I deplore this tendency (though again, there's nothing wrong with straightforward factual comparisons), not merely because it's rude, but also because it's dangerous for a project to start believing its own hype and thereby ignore the ways in which the competition may actually be superior. In general, watch out for the effect that marketing statements can have on your own development community. People may be so excited at being backed by marketing dollars that they lose objectivity about their software's true strengths and weaknesses. It is normal, and even expected, for a company's developers to exhibit a certain detachment toward marketing statements, even in public forums. Clearly, they should not come out and contradict the marketing message directly (unless it's actually wrong, though one hopes that sort of thing would have been caught earlier). But they may poke fun at it from time to time, as a way of bringing the rest of the development community back down to earth.

Don't fall into the trap of writing everything as though it were a cell phone text message. Write in complete sentences, capitalizing the first word of each sentence, and use paragraph breaks where needed. This is most important in emails and other composed writings. In IRC or similarly ephemeral forums, it's generally okay to leave out capitalization, use compressed forms of common expressions, etc. Just don't carry those habits over into more formal, persistent forums. Emails, documentation, bug reports, and other pieces of writing that are intended to have a permanent life should be written using standard grammar and spelling, and have a coherent narrative structure. This is not because there's anything inherently good about following arbitrary rules, but rather that these rules are not arbitrary: they evolved into their present forms because they make text more readable, and you should adhere to them for that reason. Readability is desirable not only because it means more people will understand what you write, but because it makes you look like the sort of person who takes the time to communicate clearly: that is, someone worth paying attention to.

For email in particular, experienced open source developers have settled on certain conventions:

Send plain text mails only, not HTML, RichText, or other formats that might be opaque to text-only mail readers. Format your lines to be around 72 columns long. Don't exceed 80 columns, which has become the de facto standard terminal width (that is, some people may use wider terminals, but no one uses a narrower one). By making your lines a little less than 80 columns, you leave room for a few levels of quoting characters to be added in others' replies without forcing a rewrapping of your text.

Use real line breaks. Some mailers do a kind of fake line wrapping, whereby when you're composing an email, the display shows line breaks that aren't actually there. When the mail goes out, it may not have the line breaks you thought it had, and it will wrap awkwardly on some people's screens. If your mailer might use fake line breaks, look for a setting you can tweak to make it show the true line breaks as you compose.

When including screen output, snippets of code, or other preformatted text, offset it clearly, so that even a lazy eye can easily see the boundaries between your prose and the material you're quoting. (I never expected to write that advice when I started this book, but on a number of open source mailing lists lately, I've seen people mix texts from different sources without making it clear which is which. The effect is very frustrating. It makes their posts significantly harder to understand, and frankly makes those people look a little bit disorganized.)

When quoting someone else's mail, insert your responses where they're most appropriate, at several different places if necessary, and trim off the parts of their mail you didn't use. If you're writing a quick comment that applies to their entire post, it's okay to top-post (that is, to put your response above the quoted text of their mail); otherwise, you should quote the relevant portion of the original text first, followed by your response.

Construct the subject lines of new mails carefully. It's the most important line in your mail, because it allows each other person in the project to decide whether or not to read more. Modern mail reading software organizes groups of related messages into threads, which can be defined not only by a common subject, but by various other headers (which are sometimes not displayed). It follows that if a thread starts to drift to a new topic, you can—and should—adjust the subject line accordingly when replying. The thread's integrity will be preserved, due to those other headers, but the new subject will help people looking at an overview of the thread know that the topic has drifted. Likewise, if you really want to start a new topic, do it by posting a fresh mail, not by replying to an existing mail and changing the subject. Otherwise, your mail would still be grouped in to the same thread as what you're replying to, and thus fool people into thinking it's about something it's not. Again, the penalty would not only be the waste of their time, but the slight dent in your credibility as someone fluent in using communications tools.

Well-formatted mails attract readers, but content keeps them. No set of fixed rules can guarantee good content, of course, but there are some principles that make it more likely.

Make things easy for your readers. There's a ton of information floating around in any active open source project, and readers cannot be expected to be familiar with most of it—indeed, they cannot always be expected to know how to become familiar. Wherever possible, your posts should provide information in the form most convenient for readers. If you have to spend an extra two minutes to dig up the URL to a particular thread in the mailing list archives, in order to save your readers the trouble of doing so, it's worth it. If you have to spend an extra 5 or 10 minutes summarizing the conclusions so far of a complex thread, in order to give people context in which to understand your post, then do so. Think of it this way: the more successful a project, the higher the reader-to-writer ratio in any given forum. If every post you make is seen by n people, then as n rises, the worthwhileness of expending extra effort to save those people time rises with it. And as people see you imposing this standard on yourself, they will work to match it in their own communications. The result is, ideally, an increase in the global efficiency of the project: when there is a choice between n people making an effort and one person doing so, the project prefers the latter.

Don't engage in hyperbole. Exaggerating in online posts is a classic arms race. For example, a person reporting a bug may worry that the developers will not pay sufficient attention, so he'll describe it as a severe, showstopper problem that is preventing him (and all his friends/coworkers/cousins) from using the software productively, when it's actually only a mild annoyance. But exaggeration is not limited to users—programmers often do the same thing during technical debates, particularly when the disagreement is over a matter of taste rather than correctness:

The same sentiment actually becomes stronger when phrased less sharply:

You will not be able to get rid of hyperbole completely, and in general it's not necessary to do so. Compared to other forms of miscommunication, hyperbole is not globally damaging—it hurts mainly the perpetrator. The recipients can compensate, it's just that the sender loses a little more credibility each time. Therefore, for the sake of your own influence in the project, try to err on the side of moderation. That way, when you do need to make a strong point, people will take you seriously.

Edit twice. For any message longer than a medium-sized paragraph, reread it from top to bottom before sending it but after you think it's done the first time. This is familiar advice to anyone who's taken a composition class, but it's especially important in online discussion. Because the process of online composition tends to be highly discontinuous (in the course of writing a message, you may need to go back and check other mails, visit certain web pages, run a command to capture its debugging output, etc.), it's especially easy to lose your sense of narrative place. Messages that were composed discontinuously and not checked before being sent are often recognizable as such, much to the chagrin (or so one would hope) of their authors. Take the time to review what you send. The more your posts hold together structurally, the more they will be read.

After writing thousands of messages, you will probably find your style tending toward the terse. This seems to be the norm in most technical forums, and there's nothing wrong with it per se. A degree of terseness that would be unacceptable in normal social interactions is simply the default for free software hackers. Here's a response I once drew on a mailing list about some free content management software, quoted in full:

Can you possibly elaborate a bit more on exactly what problems
you ran into, etc?

Also:

What version of Slash are you using? I couldn't tell from your
original message.

Exactly how did you build the apache/mod_perl source?

Did you try the Apache 2.0 patch that was posted about on
slashcode.com?

  Shane

Now that's terse! No greeting, no sign-off other than his name, and the message itself is just a series of questions phrased as compactly as possible. His one declarative sentence was an implicit criticism of my original message. And yet, I was happy to see Shane's mail, and didn't take his terseness as a sign of anything other than him being a busy person. The mere fact that he was asking questions, instead of ignoring my post, meant that he was willing to spend some time on my problem.

Will all readers react positively to this style? Not necessarily; it depends on the person and the context. For example, if someone has just posted acknowledging that she made a mistake (perhaps she wrote a bug), and you know from past experience that this person tends to be a bit insecure, then while you may still write a compact response, you should make sure to leaven it with some sort of acknowledgment of her feelings. The bulk of your response might be a brief, engineer's-eye analysis of the situation, as terse as you want. But at the end, sign off with something indicating that your terseness is not to be taken as coldness. For example, if you've just given reams of advice about exactly how the person should fix the bug, then sign off with "Good luck, <your name here>" to indicate that you wish them well and are not mad. A strategically placed smiley face or other emoticlue can often be enough to reassure an interlocutor, too.

It may seem odd to focus as much on the participant's feelings as on the surface of what they say, but to put it baldly, feelings affect productivity. Feelings are important for other reasons too, but even confining ourselves to purely utilitarian grounds, we may note that unhappy people write worse software, and less of it. Given the restricted nature of most electronic media, though, there will often be no overt clue as to how a person is feeling. You will have to make an educated guess based on a) how most people would feel in that situation, and b) what you know of this particular person from past interactions. Some people prefer a more hands-off attitude, and simply deal with everyone at face value, the idea being that if a participant doesn't say outright that she feels a particular way, then one has no business treating her as though she does. I don't buy this approach, for a couple of reasons. One, people don't behave that way in real life, so why would they online? Two, since most interactions take place in public forums, people tend to be even more restrained in expressing emotions than they might be in private. To be more precise, they are often willing to express emotions directed at others, such as gratitude or outrage, but not emotions directed inwardly, such as insecurity or pride. Yet most humans work better when they know that others are aware of their state of mind. By paying attention to small clues, you can usually guess right most of the time, and motivate people to stay involved to a greater degree than they otherwise might.

I don't mean, of course, that your role is to be a group therapist, constantly helping everyone to get in touch with their feelings. But by paying careful attention to long-term patterns in people's behavior, you will begin to get a sense of them as individuals even if you never meet them face-to-face. And by being sensitive to the tone of your own writing, you can have a surprising amount of influence over how others feel, to the ultimate benefit of the project.

One of the defining characteristics of open source culture is its distinctive notions of what does and does not constitute rudeness. While the conventions described below are not unique to free software development, nor even to software in general—they would be familiar to anyone working in mathematics, the hard sciences, or engineering disciplines—free software, with its porous boundaries and constant influx of newcomers, is an environment where these conventions are especially likely to be encountered by people unfamiliar with them.

Let's start with the things that are not rude:

Technical criticism, even when direct and unpadded, is not rude. Indeed, it can be a form of flattery: the critic is saying, by implication, that the target is worth taking seriously, and is worth spending some time on. That is, the more viable it would have been to simply ignore someone's post, the more of a compliment it becomes to take the time to criticize it (unless the critique descends into an ad hominem attack or some other form of obvious rudeness, of course).

Blunt, unadorned questions, such as Shane's questions to me in the previously quoted email, are not rude either. Questions that in other contexts might seem cold, rhetorical, or even mocking, are often intended seriously, and have no hidden agenda other than eliciting information as quickly as possible. The famous technical support question "Is your computer plugged in?" is a classic example of this. The support person really does need to know if your computer is plugged in, and after the first few days on the job, has gotten tired of prefixing her question with polite blandishments ("I beg your pardon, I just want to ask a few simple questions to rule out some possibilities. Some of these might seem pretty basic, but bear with me..."). At this point, she doesn't bother with the padding anymore, she just asks straight out: is it plugged in or not? Equivalent questions are asked all the time on free software mailing lists. The intent is not to insult the recipient, but to quickly rule out the most obvious (and perhaps most common) explanations. Recipients who understand this and react accordingly win points for taking a broad-minded view without prompting. But recipients who react badly should not be reprimanded, either. It's just a collision of cultures, not anyone's fault. Explain amiably that your question (or criticism) had no hidden meanings; it was just meant to get (or transmit) information as efficiently as possible, nothing more.

So what is rude?

By the same principle under which detailed technical criticism is a form of flattery, failure to provide quality criticism can be a kind of insult. I don't mean simply ignoring someone's work, be it proposal, code change, new issue filing, or whatever. Unless you explicitly promised a detailed reaction in advance, it's usually okay to simply not react at all. People will assume you just didn't have time to say anything. But if you do react, don't skimp: take the time to really analyze things, provide concrete examples where appropriate, dig around in the archives to find related posts from the past, etc. Or if you don't have time to put in that kind of effort, but still need to write some sort of brief response, then state the shortcoming openly in your message ("I think there's an issue filed for this, but unfortunately didn't have time to search for it, sorry"). The main thing is to recognize the existence of the cultural norm, either by fulfilling it or by openly acknowledging that one has fallen short this time. Either way, the norm is strengthened. But failing to meet that norm, while at the same time not explaining why you failed to meet it, is like saying the topic (and those participating in it) was not worth much of your time. Better to show that your time is valuable by being terse than by being lazy.

There are many other forms of rudeness, of course, but most of them are not specific to free software development, and common sense is a good enough guide to avoid them. See also la section intitulée « Tuez l'agressivité dans l'oeuf » in Chapitre 2, Genèse d'un projet, if you haven't already.

There is a region in the human brain devoted specifically to recognizing faces. It is known informally as the "fusiform face area," and its capabilities are mostly inborn, not learned. It turns out that recognizing individual people is such a crucial survival skill that we have evolved specialized hardware to do it.

Internet-based collaboration is therefore psychologically odd, because it involves tight cooperation between human beings who almost never get to identify each other by the most natural, intuitive methods: facial recognition first of all, but also sound of voice, posture, etc. To compensate for this, try to use a consistent screen name everywhere. It should be the front part of your email address (the part before the @-sign), your IRC username, your repository committer name, your issue tracker username, and so on. This name is your online "face": a short identifying string that serves some of the same purpose as your real face, although it does not, unfortunately, stimulate the same built-in hardware in the brain.

The screen name should be some intuitive permutation of your real name (mine, for example, is "kfogel"). In some situations it will be accompanied by your full name anyway, for example in mail headers:

From: "Karl Fogel" <kfogel@whateverdomain.com>

Actually, there are two things going on in that example. As mentioned earlier, the screen name matches the real name in an intuitive way. But also, the real name is real. That is, it's not some made-up appellation like:

From: "Wonder Hacker" <wonderhacker@whateverdomain.com>

There's a famous cartoon by Paul Steiner, from the July 5, 1993 issue of The New Yorker, that shows one dog logged into a computer terminal, looking down and telling another conspiratorially: "On the Internet, nobody knows you're a dog." This kind of thought probably lies behind a lot of the self-aggrandizing, meant-to-be-hip online identities people give themselves—as if calling oneself "Wonder Hacker" will actually cause people to believe one is a wonderful hacker. But the fact remains: even if no one knows you're a dog, you're still a dog. A fantastical online identity never impresses readers. Instead, it makes them think you're more into image than substance, or that you're simply insecure. Use your real name for all interactions, or if for some reason you require anonymity, then make up a name that sounds like a perfectly normal real name, and use it consistently.

In addition to keeping your online face consistent, there are some things you can do to make it more attractive. If you have an official title (e.g., "doctor", "professor", "director"), don't flaunt it, nor even mention it except when it's directly relevant to the conversation. Hackerdom in general, and free software culture in particular, tends to view title displays as exclusionary and a sign of insecurity. It's okay if your title appears as part of a standard signature block at the end of every mail you send, just don't ever use it as a tool to bolster your position in a discussion—the attempt is guaranteed to backfire. You want folks to respect the person, not the title.

Speaking of signature blocks: keep them small and tasteful, or better yet, nonexistent. Avoid large legal disclaimers tacked on to the end of every mail, especially when they express sentiments incompatible with participation in a free software project. For example, the following classic of the genre appears at the end of every post a particular user makes to a public mailing list I'm on:

IMPORTANT NOTICE

If you have received this e-mail in error or wish to read our e-mail
disclaimer statement and monitoring policy, please refer to the
statement below or contact the sender.

This communication is from Deloitte & Touche LLP.  Deloitte &
Touche LLP is a limited liability partnership registered in England
and Wales with registered number OC303675.  A list of members' names
is available for inspection at Stonecutter Court, 1 Stonecutter
Street, London EC4A 4TR, United Kingdom, the firm's principal place of
business and registered office.  Deloitte & Touche LLP is
authorised and regulated by the Financial Services Authority.

This communication and any attachments contain information which is
confidential and may also be privileged.  It is for the exclusive use
of the intended recipient(s).  If you are not the intended
recipient(s) please note that any form of disclosure, distribution,
copying or use of this communication or the information in it or in
any attachments is strictly prohibited and may be unlawful.  If you
have received this communication in error, please return it with the
title "received in error" to IT.SECURITY.UK@deloitte.co.uk then delete
the email and destroy any copies of it.

E-mail communications cannot be guaranteed to be secure or error free,
as information could be intercepted, corrupted, amended, lost,
destroyed, arrive late or incomplete, or contain viruses.  We do not
accept liability for any such matters or their consequences.  Anyone
who communicates with us by e-mail is taken to accept the risks in
doing so.

When addressed to our clients, any opinions or advice contained in
this e-mail and any attachments are subject to the terms and
conditions expressed in the governing Deloitte & Touche LLP client
engagement letter.

Opinions, conclusions and other information in this e-mail and any
attachments which do not relate to the official business of the firm
are neither given nor endorsed by it.

For someone who's just showing up to ask a question now and then, that huge disclaimer looks a bit silly but probably doesn't do any lasting harm. However, if this person wanted to participate actively in the project, that legal boilerplate would start to have a more insidious effect. It would send at least two potentially destructive signals: first, that this person doesn't have full control over his tools—he's trapped inside some corporate mailer that tacks an annoying message to the end of every email, and he hasn't got any way to route around it—and second, that he has little or no organizational support for his free software activities. True, the organization has clearly not banned him outright from posting to public lists, but it has made his posts look distinctly unwelcoming, as though the risk of letting out confidential information must trump all other priorities.

If you work for an organization that insists on adding such signature blocks to all outgoing mail, then consider getting a free email account from, for example, gmail.google.com, www.hotmail.com, or www.yahoo.com, and using that as your address for the project.

A common pitfall in online project participation is to think that you have to respond to everything. You don't. First of all, there will usually be more threads going on than you can keep track of, at least after the project is past its first few months. Second, even in the threads that you have decided to engage in, much of what people say will not require a response. Development forums in particular tend to be dominated by three kinds of messages:

None of these inherently requires a response, particularly if you can be fairly sure, based on watching the thread so far, that someone else is likely to say what you would have said anyway. (If you're worried that you'll be caught in a wait-wait loop because all the others are using this tactic too, don't be; there's almost always someone out there who'll feel like jumping into the fray.) A response should be motivated by a definite purpose. Ask yourself first: do you know what you want to accomplish? And second: will it not get accomplished unless you say something?

Two good reasons to add your voice to a thread are a) when you see a flaw in a proposal and suspect that you're the only one who sees it, and b) when you see that miscommunication is happening between others, and know that you can fix it with a clarifying post. It's also generally fine to post just to thank someone for doing something, or to say "Me too!", because a reader can tell right away that such posts do not require any response or further action, and therefore the mental effort demanded by the post ends cleanly when the reader reaches the last line of the mail. But even then, think twice before saying something; it's always better to leave people wishing you'd post more than wishing you'd post less. (See the second half of Annexe C, Why Should I Care What Color the Bikeshed Is? for more thoughts about how to behave on a busy mailing list.)

On a busy mailing list, you have two imperatives. One, obviously, is to figure out what you need to pay attention to and what you can ignore. The other is to behave in a way that avoids causing noise: not only do you want your own posts to have a high signal/noise ratio, you also want them to be the sorts of messages that stimulate other people to either post with a similarly high signal/noise ratio, or not post at all.

To see how to do that, let's consider the context in which it is done. What are some of the hallmarks of an unproductive thread?

Just because a thread is not productive at first doesn't mean it's a waste of time. It might be about an important topic, in which case the fact that it's not making any headway is all the more troublesome.

Guiding a thread toward usefulness without being pushy is an art. It won't work to simply admonish people to stop wasting their time, or to ask them not to post unless they have something constructive to say. You may, of course, think these things privately, but if you say them out loud then you will be offensive. Instead, you have to suggest conditions for further progress—give people a route, a path to follow that leads to the results you want, yet without sounding like you're dictating conduct. The distinction is largely one of tone. For example, this is bad:

Whereas this is good:

Contrast the second approach with the first. The second way does not draw a line between you and the others, or accuse them of taking the discussion into a spiral. It talks about "we", which is important whether or not you actually participated in the thread before now, because it reminds everyone that even those who have been silent thus far still have a stake in the thread's outcome. It describes why the thread is going nowhere, but does so without pejoratives or judgements—it just dispassionately states some facts. Most importantly, it offers a positive course of action, so that instead of people feeling like discussion is being closed off (a restriction against which they can only be tempted to rebel), they will feel as if they're being offered a way to take the conversation to a more constructive level. This is a standard people will naturally want to meet.

You won't always want a thread to make it to the next level of constructiveness—sometimes you'll want it to just go away. The purpose of your post, then, is to make it do one or the other. If you can tell from the way the thread has gone so far that no one is actually going to take the steps you suggested, then your post effectively shuts down the thread without seeming to do so. Of course, there isn't any foolproof way to shut down a thread, and even if there were, you wouldn't want to use it. But asking participants to either make visible progress or stop posting is perfectly defensible, if done diplomatically. Be wary of quashing threads prematurely, however. Some amount of speculative chatter can be productive, depending on the topic, and asking for it to be resolved too quickly will stifle the creative process, as well as make you look impatient.

Don't expect any thread to stop on a dime. There will probably still be a few posts after yours, either because mails got crossed in the pipe, or because people want to have the last word. This is nothing to worry about, and you don't need to post again. Just let the thread peter out, or not peter out, as the case may be. You can't have complete control; on the other hand, you can expect to have a statistically significant effect across many threads.

Although discussion can meander in any topic, the probability of meandering goes up as the technical difficulty of the topic goes down. After all, the greater the technical difficulty, the fewer participants can really follow what's going on. Those who can are likely to be the most experienced developers, who have already taken part in such discussions thousands of times before, and know what sort of behavior is likely to lead to a consensus everyone can live with.

Thus, consensus is hardest to achieve in technical questions that are simple to understand and easy to have an opinion about, and in "soft" topics such as organization, publicity, funding, etc. People can participate in those arguments forever, because there are no qualifications necessary for doing so, no clear ways to decide (even afterward) if a decision was right or wrong, and because simply outwaiting other discussants is sometimes a successful tactic.

The principle that the amount of discussion is inversely proportional to the complexity of the topic has been around for a long time, and is known informally as the Bikeshed Effect. Here is Poul-Henning Kamp's explanation of it, from a now-famous post made to BSD developers:

(His complete post is very much worth reading, too. See Annexe C, Why Should I Care What Color the Bikeshed Is?; see also http://bikeshed.com.)

Anyone who's ever taken regular part in group decision-making will recognize what Kamp is talking about. However, it is usually impossible to persuade everyone to avoid painting bikesheds. The best you can do is point out that the phenomenon exists, when you see it happening, and persuade the senior developers—the people whose posts carry the most weight—to drop their paintbrushes early, so at least they're not contributing to the noise. Bikeshed painting parties will never go away entirely, but you can make them shorter and less frequent by spreading an awareness of the phenomenon in the project's culture.

A holy war is a dispute, often but not always over a relatively minor issue, which is not resolvable on the merits of the arguments, but where people feel passionate enough to continue arguing anyway in the hope that their side will prevail. Holy wars are not quite the same as bikeshed paintings. People painting bikesheds are usually quick to jump in with an opinion (because they can), but they won't necessarily feel strongly about it, and indeed will sometimes express other, incompatible opinions, to show that they understand all sides of the issue. In a holy war, on the other hand, understanding the other sides is a sign of weakness. In a holy war, everyone knows there is One Right Answer; they just don't agree on what it is.

Once a holy war has started, it generally cannot be resolved to everyone's satisfaction. It does no good to point out, in the midst of a holy war, that a holy war is going on. Everyone knows that already. Unfortunately, a common feature of holy wars is disagreement on the very question of whether the dispute is resolvable by continued discussion. Viewed from outside, it is clear that neither side is changing the other's mind. Viewed from inside, the other side is being obtuse and not thinking clearly, but they might come around if browbeaten enough. Now, I am not saying there's never a right side in a holy war. Sometimes there is—in the holy wars I've participated in, it's always been my side, of course. But it doesn't matter, because there's no algorithm for convincingly demonstrating that one side or the other is right.

A common, but unsatisfactory, way people try to resolve holy wars is to say "We've already spent far more time and energy discussing this than it's worth! Can we please just drop it?" There are two problems with this. First, that time and energy has already been spent and can never be recovered—the only question now is, how much more effort remains? If some people feel that just a little more discussion will bring the issue to a close, then it still makes sense (from their point of view) to continue.

The other problem with asking for the matter to be dropped is that this is often equivalent to allowing one side, the status quo, to declare victory by inaction. And in some cases, the status quo is known to be unacceptable anyway: everyone agrees that some decision must be made, some action taken. Dropping the subject would be worse for everyone than simply giving up the argument would be for anyone. But since that dilemma applies to all equally, it's still possible to end up arguing forever about what to do.

So how should you handle holy wars?

The first answer is, try to set things up so they don't happen. This is not as hopeless as it sounds:

You can anticipate certain standard holy wars: they tend to come up over programming languages, licenses (see la section intitulée « The GPL and License Compatibility » in Chapitre 9, Licenses, Copyrights, and Patents), reply-to munging (see la section intitulée « Le grand débat du « Répondre à » » in Chapitre 3, L'infrastructure technique), and a few other topics. Each project usually has a holy war or two all its own, as well, which longtime developers will quickly become familiar with. The techniques for stopping holy wars, or at least limiting their damage, are pretty much the same everywhere. Even if you are positive your side is right, try to find some way to express sympathy and understanding for the points the other side is making. Often the problem in a holy war is that because each side has built its walls as high as possible, and made it clear that any other opinion is sheer foolishness, the act of surrendering or changing one's mind becomes psychologically unbearable: it would be an admission not just of being wrong, but of having been certain and still being wrong. The way you can make this admission palatable for the other side is to express some uncertainty yourself—precisely by showing that you understand the arguments they are making and find them at least sensible, if not finally persuasive. Make a gesture that provides space for a reciprocal gesture, and usually the situation will improve. You are no more or less likely to get the technical result you wanted, but at least you can avoid unnecessary collateral damage to the project's morale.

When a holy war can't be avoided, decide early how much you care, and then be willing to publicly give up. When you do so, you can say that you're backing out because the holy war isn't worth it, but don't express any bitterness and don't take the opportunity for a last parting shot at the opposing side's arguments. Giving up is effective only when done gracefully.

Programming language holy wars are a bit of a special case, because they are often highly technical, yet many people feel qualified to take part in them, and the stakes are very high, since the result may determine what language a good portion of the project's code is written in. The best solution is to choose the language early, with buy-in from influential initial developers, and then defend it on the grounds that it's what you are all comfortable writing in, not on the grounds that it's better than some other language that could have been used instead. Never let the conversation degenerate into an academic comparison of programming languages (this seems to happen especially often when someone brings up Perl, for some reason); that's a death topic that you must simply refuse to be drawn into.

For more historical background on holy wars, see http://catb.org/~esr/jargon/html/H/holy-wars.html, and the paper by Danny Cohen that popularized the term, http://www.ietf.org/rfc/ien/ien137.txt.

In any mailing list discussion, it's easy for a small minority to give the impression that there is a great deal of dissent, by flooding the list with numerous lengthy emails. It's a bit like a filibuster, except that the illusion of widespread dissent is even more powerful, because it's divided across an arbitrary number of discrete posts and most people won't bother to keep track of who said what, when. They'll just have an instinctive impression that the topic is very controversial, and wait for the fuss to die down.

The best way to counteract this effect is to point it out very clearly and provide supporting evidence showing how small the actual number of dissenters is, compared to those in agreement. In order to increase the disparity, you may want to privately poll people who have been mostly silent, but who you suspect would agree with the majority. Don't say anything that suggests the dissenters were deliberately trying to inflate the impression they were making. Chances are they weren't, and even if they were, there would be no strategic advantage to pointing it out. All you need do is show the actual numbers in a side-by-side comparison, and people will realize that their intuition of the situation does not match reality.

This advice doesn't just apply to issues with clear for-and-against positions. It applies to any discussion where a fuss is being made, but it's not clear that most people consider the issue under discussion to be a real problem. After a while, if you agree that the issue is not worthy of action, and can see that it has failed to get much traction (even if it has generated a lot of mails), you can just observe publicly that it's not getting traction. If the "Noisy Minority" effect has been at work, your post will seem like a breath of fresh air. Most people's impression of the discussion up to that point will have been somewhat murky: "Huh, it sure feels like there's some big deal here, because there sure are a lot of posts, but I can't see any clear progress happening." By explaining how the form of the discussion made it appear more turbulent than it really was, you retrospectively give it a new shape, through which people can recast their understanding of what transpired.

To counteract such behavior, it helps to understand the mentality of those who engage in it. People generally do not do it consciously. No one wakes up in the morning and says to himself: "Today I'm going to cynically manipulate procedural forms in order to be an irritating obstructionist." Instead, such actions are often preceded by a semi-paranoid feeling of being shut out of group interactions and decisions. The person feels he is not being taken seriously, or (in the more severe cases) that there is almost a conspiracy against him—that the other project members have decided to form an exclusive club, of which he is not a member. This then justifies, in his mind, taking rules literally and engaging in a formal manipulation of the project's procedures, in order to make everyone else take him seriously. In extreme cases, the person can even believe that he is fighting a lonely battle to save the project from itself.

It is the nature of such an attack from within that not everyone will notice it at the same time, and some people may not see it at all unless presented with very strong evidence. This means that neutralizing it can be quite a bit of work. It's not enough to persuade yourself that it's happening; you have to marshal enough evidence to persuade others too, and then you have to distribute that evidence in a thoughtful way.

Given that it's so much work to fight, it's often better just to tolerate it for a while. Think of it like a parasitic but mild disease: if it's not too debilitating, the project can afford to remain infected, and medicine might have harmful side effects. However, if it gets too damaging to tolerate, then it's time for action. Start gathering notes on the patterns you see. Make sure to include references to public archives—this is one of the reasons the project keeps records, so you might as well use them. Once you've got a good case built, start having private conversations with other project participants. Don't tell them what you've observed; instead, first ask them what they've observed. This may be your last chance to get unfiltered feedback about how others see the troublemaker's behavior; once you start openly talking about it, opinion will become polarized and no one will be able to remember what he formerly thought about the matter.

If private discussions indicate that at least some others see the problem too, then it's time to do something. That's when you have to get really cautious, because it's very easy for this sort of person to try to make it appear as though you're picking on them unfairly. Whatever you do, never accuse them of maliciously abusing the project's procedures, of being paranoid, or, in general, of any of the other things that you suspect are probably true. Your strategy should be to look both more reasonable and more concerned with the overall welfare of the project, with the goal of either reforming the person's behavior, or getting them to go away permanently. Depending on the other developers, and your relationship with them, it may be advantageous to gather allies privately first. Or it may not; that might just create ill will behind the scenes, if people think you're engaging in an improper whispering campaign.

Remember that although the other person may be the one behaving destructively, you will be the one who appears destructive if you make a public charge that you can't back up. Be sure to have plenty of examples to demonstrate what you're saying, and say it as gently as possible while still being direct. You may not persuade the person in question, but that's okay as long as you persuade everyone else.

I remember only one situation, in more than 10 years of working in free software, where things got so bad that we actually had to ask someone to stop posting altogether. As is so often the case, he was not rude, and sincerely wanted only to be helpful. He just didn't know when to post and when not to post. Our lists were open to the public, and he was posting so often, and asking questions on so many different topics, that it was getting to be a noise problem for the community. We'd already tried asking him nicely to do a little more research for answers before posting, but that had no effect.

The strategy that finally worked is a perfect example of how to build a strong case on neutral, quantitative data. One of our developers did some digging in the archives, and then sent the following message privately to a few developers. The offender (the third name on the list below, shown here as "J. Random") had very little history with the project, and had contributed no code or documentation. Yet he was the third most active poster on the mailing lists:

From: "Brian W. Fitzpatrick" <fitz@collab.net>
To: [... recipient list omitted for anonymity ...]
Subject: The Subversion Energy Sink
Date: Wed, 12 Nov 2003 23:37:47 -0600

In the last 25 days, the top 6 posters to the svn [dev|users] list have
been:

    294  kfogel@collab.net
    236  "C. Michael Pilato" <cmpilato@collab.net>
    220  "J. Random" <jrandom@problematic-poster.com>
    176  Branko Čibej <brane@xbc.nu>
    130  Philip Martin <philip@codematters.co.uk>
    126  Ben Collins-Sussman <sussman@collab.net>

I would say that five of these people are contributing to Subversion
hitting 1.0 in the near future.

I would also say that one of these people is consistently drawing time
and energy from the other 5, not to mention the list as a whole, thus
(albeit unintentionally) slowing the development of Subversion.  I did
not do a threaded analysis, but vgrepping my Subversion mail spool tells
me that every mail from this person is responded to at least once by at
least 2 of the other 5 people on the above list.

I think some sort of radical intervention is necessary here, even if we
do scare the aforementioned person away.  Niceties and kindness have
already proven to have no effect.

dev@subversion is a mailing list to facilitate development of a version
control system, not a group therapy session.

-Fitz, attempting to wade through three days of svn mail that he let
 pile up

Though it might not seem so at first, J. Random's behavior was a classic case of abusing project procedures. He wasn't doing something obvious like trying to filibuster a vote, but he was taking advantage of the mailing list's policy of relying on self-moderation by its members. We left it to each individual's judgement when to post and on what topics. Thus, we had no procedural recourse for dealing with someone who either did not have, or would not exercise, such judgement. There was no rule one could point to and say the fellow was violating it, yet everyone knew that his frequent posting was getting to be a serious problem.

Fitz's strategy was, in retrospect, masterful. He gathered damning quantitative evidence, but then distributed it discreetly, sending it first to a few people whose support would be key in any drastic action. They agreed that some sort of action was necessary, and in the end we called J. Random on the phone, described the problem to him directly, and asked him to simply stop posting. He never really did understand the reasons why; if he had been capable of understanding, he probably would have exercised appropriate judgement in the first place. But he agreed to stop posting, and the mailing lists became useable again. Part of the reason this strategy worked was, perhaps, the implicit threat that we could start restricting his posts via the moderation software normally used for preventing spam (see la section intitulée « Se prémunir du spam » in Chapitre 3, L'infrastructure technique). But the reason we were able to have that option in reserve was that Fitz had gathered the necessary support from key people first.

Typically, all communications in an open source project (except sometimes IRC conversations) are archived. The archives are public and searchable, and have referential stability: that is, once a given piece of information is recorded at a particular address, it stays at that address forever.

Use those archives as much as possible, and as conspicuously as possible. Even when you know the answer to some question off the top of your head, if you think there's a reference in the archives that contains the answer, spend the time to dig it up and present it. Every time you do that in a publicly visible way, some people learn for the first time that the archives are there, and that searching in them can produce answers. Also, by referring to the archives instead of rewriting the advice, you reinforce the social norm against duplicating information. Why have the same answer in two different places? When the number of places it can be found is kept to a minimum, people who have found it before are more likely to remember what to search for to find it again. Well-placed references also contribute to the quality of search results in general, because they strengthen the targeted resource's ranking in Internet search engines.

There are times when duplicating information makes sense, however. For example, suppose there's a response already in the archives, not from you, saying:

It appears that your Scanley indexes have become frobnicated.  To
unfrobnicate them, run these steps:

1. Shut down the Scanley server.
2. Run the 'defrobnicate' program that ships with Scanley.
3. Start up the server.

Then, months later, you see another post indicating that someone's indexes have become frobnicated. You search the archives and come up with the old response above, but you realize it's missing some steps (perhaps by mistake, or perhaps because the software has changed since that post was written). The classiest way to handle this is to post a new, more complete set of instructions, and explicitly obsolete the old post by mentioning it:

It appears that your Scanley indexes have become frobnicated.  We
saw this problem back in July, and J. Random posted a solution at
http://blahblahblah/blah.  Below is a more complete description of
how to unfrobnicate your indexes, based on J. Random's instructions
but extending them a bit:

1. Shut down the Scanley server.
2. Become the user the Scanley server normally runs as.
3. As that user, run the 'defrobnicate' program on the indexes.
4. Run Scanley by hand to see if the indexes work now.
5. Restart the server.

(In an ideal world, it would be possible to attach a note to the old post, saying that there is newer information available and pointing to the new post. However, I don't know of any archiving software that offers an "obsoleted by" feature, perhaps because it would be mildly tricky to implement in a way that doesn't violate the archives' integrity as a verbatim record. This is another reason why creating dedicated web pages with answers to common questions is a good idea.)

Archives are probably most often searched for answers to technical questions, but their importance to the project goes well beyond that. If a project's formal guidelines are its statutory law, the archives are its common law: a record of all decisions made and how they were arrived at. In any recurring discussion, it's pretty much obligatory nowadays to start with an archive search. This allows you to begin the discussion with a summary of the current state of things, anticipate objections, prepare rebuttals, and possibly discover angles you hadn't thought of. Also, the other participants will expect you to have done an archive search. Even if the previous discussions went nowhere, you should include pointers to them when you re-raise the topic, so people can see for themselves a) that they went nowhere, and b) that you did your homework, and therefore are probably saying something now that has not been said before.

<a name="mylabel">...</a>

<p id="mylabel">...</p>

http://myproject.example.com/faq.html#mylabel

<a name="mylabel"></a>

<a name="mylabel" title="#mylabel">...</a>

As a project acquires history and complexity, the amount of data each incoming participant must absorb increases. Those who have been with the project a long time were able to learn, and invent, the project's conventions as they went along. They will often not be consciously aware of what a huge body of tradition has accumulated, and may be surprised at how many missteps recent newcomers seem to make. Of course, the issue is not that the newcomers are of any lower quality than before; it's that they face a bigger acculturation burden than newcomers did in the past.

The traditions a project accumulates are as much about how to communicate and preserve information as they are about coding standards and other technical minutae. We've already looked at both sorts of standards, in la section intitulée « La documentation développeurs » in Chapitre 2, Genèse d'un projet and la section intitulée « Writing It All Down » in Chapitre 4, Social and Political Infrastructure respectively, and examples are given there. What this section is about is how to keep such guidelines up-to-date as the project evolves, especially guidelines about how communications are managed, because those are the ones that change the most as the project grows in size and complexity.

First, watch for patterns in how people get confused. If you see the same situations coming up over and over, especially with new participants, chances are there is a guideline that needs to be documented but isn't. Second, don't get tired of saying the same things over and over again, and don't sound like you're tired of saying them. You and other project veterans will have to repeat yourselves often; this is an inevitable side effect of the arrival of newcomers.

Every web page, every mailing list message, and every IRC channel should be considered advertising space—not for commercial advertisements, but for ads about your project's own resources. What you put in that space depends on the demographics of those likely to read it. An IRC channel for user questions, for example, is likely to get people who have never interacted with the project before—often someone who has just installed the software, and has a question he'd like answered immediately (after all, if it could wait, he'd have sent it to a mailing list instead, which would probably use less of his total time, although it would take longer for an answer to come back). People usually don't make a permanent investment in the IRC channel; they'll show up, ask their question, and leave.

Therefore, the channel topic should be aimed at people looking for technical answers about the software right now, rather than at, say, people who might get involved with the project in a long term way and for whom community interaction guidelines might be more appropriate. Here's how a really busy channel handles it (compare this with the earlier example in la section intitulée « IRC / Real-Time Chat Systems » in Chapitre 3, L'infrastructure technique):

You are now talking on #linuxhelp

Topic for #linuxhelp is Please READ
http://www.catb.org/~esr/faqs/smart-questions.html &&
http://www.tldp.org/docs.html#howto BEFORE asking questions | Channel
rules are at http://www.nerdfest.org/lh_rules.html | Please consult
http://kerneltrap.org/node/view/799 before asking about upgrading to a
2.6.x kernel | memory read possible: http://tinyurl.com/4s6mc ->
update to 2.6.8.1 or 2.4.27 | hash algo disaster: http://tinyurl.com/6w8rf
| reiser4 out

With mailing lists, the "ad space" is a tiny footer appended to every message. Most projects put subscription/unsubscription instructions there, and perhaps a pointer to the project's home page or FAQ page as well. You might think that anyone subscribed to the list would know where to find those things, and they probably do—but many more people than just subscribers see those mailing list messages. An archived post may be linked to from many places; indeed, some posts become so widely known that they eventually have more readers off the list than on it.

Formatting can make a big difference. For example, in the Subversion project, we were having limited success using the bug-filtering technique described in la section intitulée « Pre-Filtering the Bug Tracker » in Chapitre 3, L'infrastructure technique. Many bogus bug reports were still being filed by inexperienced people, and each time it happened, the filer had to be educated in exactly the same way as the 500 people before him. One day, after one of our developers had finally gotten to the end of his rope and flamed some poor user who didn't read the issue tracker guidelines carefully enough, another developer decided this pattern had gone on long enough. He suggested that we reformat the issue tracker front page so that the most important part, the injunction to discuss the bug on the mailing lists or IRC channels before filing, would stand out in huge, bold red letters, on a bright yellow background, centered prominently above everything else on the page. We did so (you can see the results at http://subversion.tigris.org/project_issues.html), and the result was a noticeable drop in the rate of bogus issue filings. We still get them, of course—we always will—but the rate has slowed considerably, even as the number of users increases. The outcome is not only that the bug database contains less junk, but that those who respond to issue filings stay in a better mood, and are more likely to remain friendly when responding to one of the now-rare bogus filings. This improves both the project's image and the mental health of its volunteers.

The lesson for us was that merely writing up the guidelines was not enough. We also had to put them where they'd be seen by those who need them most, and format them in such a way that their status as introductory material would be immediately clear to people unfamiliar with the project.

Static web pages are not the only venue for advertising the project's customs. A certain amount of interactive policing (in the friendly-reminder sense, not the handcuffs-and-jail sense) is also required. All peer review, even the commit reviews described in la section intitulée « Pratiquez la revue par pairs » in Chapitre 2, Genèse d'un projet, should include review of people's conformance or non-conformance with project norms, especially with regard to communications conventions.

Another example from the Subversion project: we settled on a convention of "r12908" to mean "revision 12908 in the version control repository." The lower-case "r" prefix is easy to type, and because it's half the height of the digits, it makes an easily-recognizable block of text when combined with the digits. Of course, settling on the convention doesn't mean that everyone will begin using it consistently right away. Thus, when a commit mail comes in with a log message like this:

------------------------------------------------------------------------
r12908 | qsimon | 2005-02-02 14:15:06 -0600 (Wed, 02 Feb 2005) | 4 lines

Patch from J. Random Contributor <jrcontrib@gmail.com>

* trunk/contrib/client-side/psvn/psvn.el:
  Fixed some typos from revision 12828.
------------------------------------------------------------------------

...part of reviewing that commit is to say "By the way, please use 'r12828', not 'revision 12828' when referring to past changes." This isn't just pedantry; it's important as much for automatic parsability as for human readership.

By following the general principle that there should be canonical referral methods for common entities, and that these referral methods should be used consistently everywhere, the project in effect exports certain standards. Those standards enable people to write tools that present the project's communications in more useable ways—for example, a revision formatted as "r12828" could be transformed into a live link into the repository browsing system. This would be harder to do if the revision were written as "revision 12828", both because that form could be divided across a line break, and because it's less distinct (the word "revision" will often appear alone, and groups of numbers will often appear alone, whereas the combination "r12828" can only mean a revision number). Similar concerns apply to issue numbers, FAQ items (hint: use a URL with a named anchor, as described in Named Anchors and ID Attributes), etc.

Even for entities where there is not an obvious short, canonical form, people should still be encouraged to provide key pieces of information consistently. For example, when referring to a mailing list message, don't just give the sender and subject; also give the archive URL and the Message-ID header. The last allows people who have their own copy of the mailing list (people sometimes keep offline copies, for example to use on a laptop while traveling) to unambiguously identify the right message even if they don't have access to the archives. The sender and subject wouldn't be enough, because the same person might make several posts in the same thread, even on the same day.

The more a project grows, the more important this sort of consistency becomes. Consistency means that everywhere people look, they see the same patterns being followed, so they know to follow those patterns themselves. This, in turn, reduces the number of questions they need to ask. The burden of having a million readers is no greater than that of having one; scalability problems start to arise only when a certain percentage of those readers ask questions. As a project grows, therefore, it must reduce that percentage by increasing the density and accessibility of information, so that any given person is more likely to find what he needs without having to ask.

Handling a security vulnerability is different from handling any other kind of bug report. In free software, doing things openly and transparently is normally almost a religious credo. Every step of the standard bug-handling process is visible to all who care to watch: the arrival of the initial report, the ensuing discussion, and the eventual fix.

Security bugs are different. They can compromise users' data, and possibly users' entire computers. To discuss such a problem openly would be to advertise its existence to the entire world—including to all the parties who might make malicious use of the bug. Even merely committing a fix effectively announces the bug's existence (there are potential attackers who watch the commit logs of public projects, systematically looking for changes that indicate security problems in the pre-change code). Most open source projects have settled on approximately the same set of steps to handle this conflict between openness and secrecy, based on the these basic guidelines:

In practice, those principles lead to a fairly standardized series of steps, which are described in the sections below.

From: Your Name Here
To: admin@large-famous-server.com
Reply-to: Your Name Here (not the security list's address)
Subject: Confidential Scanley vulnerability notification.


This email is a confidential pre-notification of a security alert
in the Scanley server.

Please *do not forward* any part of this mail to anyone.  The public
announcement is not until May 19th, and we'd like to keep the
information embargoed until then.

You are receiving this mail because (we think) you run a Scanley
server, and would want to have it patched before this security hole is
made public on May 19th.

References:
===========

   CAN-2004-1771: Scanley stack overflow in queries

Vulnerability:
==============

   The server can be made to run arbitrary commands if the server's
   locale is misconfigured and the client sends a malformed query.

Severity:
=========

   Very severe, can involve arbitrary code execution on the server.

Workarounds:
============

   Setting the 'natural-language-processing' option to 'off' in
   scanley.conf closes this vulnerability.

Patch:
======

   The patch below applies to Scanley 3.0, 3.1, and 3.2.

   A new public release (Scanley 3.2.1) will be made on or just before
   May 19th, so that it is available at the same time as this
   vulnerability is made public.  You can patch now, or just wait for
   the public release.  The only difference between 3.2 and 3.2.1 will
   be this patch.

[...patch goes here...]

This section describes the formal conventions of release numbering in detail, and assumes very little prior knowledge. It is intended mainly as a reference. If you're already familiar with these conventions, you can skip this section.

Release numbers are groups of digits separated by dots:

...and so on. The dots are not decimal points, they are merely separators; "5.3.9" would be followed by "5.3.10". A few projects have occasionally hinted otherwise, most famously the Linux kernel with its "0.95", "0.96"... "0.99" sequence leading up to Linux 1.0, but the convention that the dots are not decimals is now firmly established and should be considered a standard. There is no limit to the number of components (digit portions containing no dots), but most projects do not go beyond three or four. The reasons why will become clear later.

In addition to the numeric components, projects sometimes tack on a descriptive label such as "Alpha" or "Beta" (see Alpha et Bêta), for example:

An Alpha or Beta qualifier means that this release precedes a future release that will have the same number without the qualifier. Thus, "2.3.0 (Alpha)" leads eventually to "2.3.0". In order to allow several such candidate releases in a row, the qualifiers themselves can have meta-qualifiers. For example, here is a series of releases in the order that they would be made available to the public:

Notice that when it has the "Alpha" qualifier, Scanley "2.3" is written as "2.3.0". The two numbers are equivalent—trailing all-zero components can always be dropped for brevity—but when a qualifier is present, brevity is out the window anyway, so one might as well go for completeness instead.

Other qualifiers in semi-regular use include "Stable", "Unstable", "Development", and "RC" (for "Release Candidate"). The most widely used ones are still "Alpha" and "Beta", with "RC" running a close third place, but note that "RC" always includes a numeric meta-qualifier. That is, you don't release "Scanley 2.3.0 (RC)", you release "Scanley 2.3.0 (RC 1)", followed by RC2, etc.

Those three labels, "Alpha", "Beta", and "RC", are pretty widely known now, and I don't recommend using any of the others, even though the others might at first glance seem like better choices because they are normal words, not jargon. But people who install software from releases are already familiar with the big three, and there's no reason to do things gratuitously differently from the way everyone else does them.

Although the dots in release numbers are not decimal points, they do indicate place-value significance. All "0.X.Y" releases precede "1.0" (which is equivalent to "1.0.0", of course). "3.14.158" immediately precedes "3.14.159", and non-immediately precedes "3.14.160" as well as "3.15.anything", and so.

A consistent release numbering policy enables a user to look at two release numbers for the same piece of software and tell, just from the numbers, the important differences between those two releases. In a typical three-component system, the first component is the major number, the second is the minor number, and the third is the micro number. For example, release "2.10.17" is the seventeenth micro release in the tenth minor release line within the second major release series. The words "line" and "series" are used informally here, but they mean what one would expect. A major series is simply all the releases that share the same major number, and a minor series (or minor line) consists of all the releases that share the same minor and major number. That is, "2.4.0" and "3.4.1" are not in the same minor series, even though they both have "4" for their minor number; on the other hand, "2.4.0" and "2.4.2" are in the same minor line, though they are not adjacent if "2.4.1" was released between them.

The meanings of these numbers are exactly what you'd expect: an increment of the major number indicates that major changes happened; an increment of the minor number indicates minor changes; and an increment of the micro number indicates really trivial changes. Some projects add a fourth component, usually called the patch number, for especially fine-grained control over the differences between their releases (confusingly, other projects use "patch" as a synonym for "micro" in a three-component system). There are also projects that use the last component as a build number, incremented every time the software is built and representing no change other than that build. This helps the project link every bug report with a specific build, and is probably most useful when binary packages are the default method of distribution.

Although there are many different conventions for how many components to use, and what the components mean, the differences tend to be minor—you get a little leeway, but not a lot. The next two sections discuss some of the most widely used conventions.

Most projects have rules about what kinds of changes are allowed into a release if one is only incrementing the micro number, different rules for the minor number, and still different ones for the major number. There is no set standard for these rules yet, but here I will describe a policy that has been used successfully by multiple projects. You may want to just adopt this policy in your own project, but even if you don't, it's still a good example of the kind of information release numbers should convey. This policy is adapted from the numbering system used by the APR project, see http://apr.apache.org/versioning.html.

What backward-compatible and forward-compatible mean, exactly, depends on what your software does, but in context they are usually not open to much interpretation. For example, if your project is a client/server application, then "backward-compatible" means that upgrading the server to 2.6.0 should not cause any existing 2.5.4 clients to lose functionality or behave differently than they did before (except for bugs that were fixed, of course). On the other hand, upgrading one of those clients to 2.6.0, along with the server, might make new functionality available for that client, functionality that 2.5.4 clients don't know how to take advantage of. If that happens, then the upgrade is not "forward-compatible": clearly you can't now downgrade that client back to 2.5.4 and keep all the functionality it had at 2.6.0, since some of that functionality was new in 2.6.0.

This is why micro releases are essentially for bug fixes only. They must remain compatible in both directions: if you upgrade from 2.5.3 to 2.5.4, then change your mind and downgrade back to 2.5.3, no functionality should be lost. Of course, the bugs fixed in 2.5.4 would reappear after the downgrade, but you wouldn't lose any features, except insofar as the restored bugs prevent the use of some existing features.

Client/server protocols are just one of many possible compatibility domains. Another is data formats: does the software write data to permanent storage? If so, the formats it reads and writes need to follow the compatibility guidelines promised by the release number policy. Version 2.6.0 needs to be able to read the files written by 2.5.4, but may silently upgrade the format to something that 2.5.4 cannot read, because the ability to downgrade is not required across a minor number boundary. If your project distributes code libraries for other programs to use, then APIs are a compatibility domain too: you must make sure that source and binary compatibility rules are spelled out in such a way that the informed user need never wonder whether or not it's safe to upgrade in place. She will be able to look at the numbers and know instantly.

In this system, you don't get a chance for a fresh start until you increment the major number. This can often be a real inconvenience: there may be features you wish to add, or protocols that you wish to redesign, that simply cannot be done while maintaining compatibility. There's no magic solution to this, except to try to design things in an extensible way in the first place (a topic easily worth its own book, and certainly outside the scope of this one). But publishing a release compatibility policy, and adhering to it, is an inescapable part of distributing software. One nasty surprise can alienate a lot of users. The policy just described is good partly because it's already quite widespread, but also because it's easy to explain and to remember, even for those not already familiar with it.

It is generally understood that these rules do not apply to pre-1.0 releases (although your release policy should probably state so explicitly, just to be clear). A project that is still in initial development can release 0.1, 0.2, 0.3, and so on in sequence, until it's ready for 1.0, and the differences between those releases can be arbitrarily large. Micro numbers in pre-1.0 releases are optional. Depending on the nature of your project and the differences between the releases, you might find it useful to have 0.1.0, 0.1.1, etc., or you might not. Conventions for pre-1.0 release numbers are fairly loose, mainly because people understand that strong compatibility constraints would hamper early development too much, and because early adopters tend to be forgiving anyway.

Remember that all these injunctions only apply to this particular three-component system. Your project could easily come up with a different three-component system, or even decide it doesn't need such fine granularity and use a two-component system instead. The important thing is to decide early, publish exactly what the components mean, and stick to it.

Some projects use the parity of the minor number component to indicate the stability of the software: even means stable, odd means unstable. This applies only to the minor number, not the major and micro numbers. Increments in the micro number still indicate bug fixes (no new features), and increments in the major number still indicate big changes, new feature sets, etc.

The advantage of the even/odd system, which has been used by the Linux kernel project among others, is that it offers a way to release new functionality for testing without subjecting production users to potentially unstable code. People can see from the numbers that "2.4.21" is okay to install on their live web server, but that "2.5.1" should probably stay confined to home workstation experiments. The development team handles the bug reports that come in from the unstable (odd-minor-numbered) series, and when things start to settle down after some number of micro releases in that series, they increment the minor number (thus making it even), reset the micro number back to "0", and release a presumably stable package.

This system preserves, or at least, does not conflict with, the compatibility guidelines given earlier. It simply overloads the minor number with some extra information. This forces the minor number to be incremented about twice as often as would otherwise be necessary, but there's no great harm in that. The even/odd system is probably best for projects that have very long release cycles, and which by their nature have a high proportion of conservative users who value stability above new features. It is not the only way to get new functionality tested in the wild, however. la section intitulée « Stabilizing a Release » later in this chapter describes another, perhaps more common, method of releasing potentially unstable code to the public, marked so that people have an idea of the risk/benefit trade-offs immediately on seeing the release's name.

The exact mechanics of creating a release branch depend on your version control system, of course, but the general concepts are the same in most systems. A branch usually sprouts from another branch or from the trunk. Traditionally, the trunk is where mainline development goes on, unfettered by release constraints. The first release branch, the one leading to the "1.0" release, sprouts off the trunk. In CVS, the branch command would be something like this

$ cd trunk-working-copy
$ cvs tag -b RELEASE_1_0_X

or in Subversion, like this:

$ svn copy http://.../repos/trunk http://.../repos/branches/1.0.x

(All these examples assume a three-component release numbering system. While I can't show the exact commands for every version control system, I'll give examples in CVS and Subversion and hope that the corresponding commands in other systems can be deduced from those two.)

Notice that we created branch "1.0.x" (with a literal "x") instead of "1.0.0". This is because the same minor line—i.e., the same branch—will be used for all the micro releases in that line. The actual process of stabilizing the branch for release is covered in la section intitulée « Stabilizing a Release » later in this chapter. Here we are concerned just with the interaction between the version control system and the release process. When the release branch is stabilized and ready, it is time to tag a snapshot from the branch:

$ cd RELEASE_1_0_X-working-copy
$ cvs tag RELEASE_1_0_0

or

$ svn copy http://.../repos/branches/1.0.x http://.../repos/tags/1.0.0

That tag now represents the exact state of the project's source tree in the 1.0.0 release (this is useful in case anyone ever needs to get an old version after the packaged distributions and binaries have been taken down). The next micro release in the same line is likewise prepared on the 1.0.x branch, and when it is ready, a tag is made for 1.0.1. Lather, rinse, repeat for 1.0.2, and so on. When it's time to start thinking about a 1.1.x release, make a new branch from trunk:

$ cd trunk-working-copy
$ cvs tag -b RELEASE_1_1_X

or

$ svn copy http://.../repos/trunk http://.../repos/branches/1.1.x

Maintenance can continue in parallel along both 1.0.x and 1.1.x, and releases can be made independently from both lines. In fact, it is not unusual to publish near-simultaneous releases from two different lines. The older series is recommended for more conservative site administrators, who may not want to make the big jump to (say) 1.1 without careful preparation. Meanwhile, more adventurous people usually take the most recent release on the highest line, to make sure they're getting the latest features, even at the risk of greater instability.

The group agrees to let one person be the release owner. This person has final say over what changes make it into the release. Of course, it is normal and expected for there to be discussions and arguments, but in the end the group must grant the release owner sufficient authority to make final decisions. For this system to work, it is necessary to choose someone with the technical competence to understand all the changes, and the social standing and people skills to navigate the discussions leading up to the release without causing too many hurt feelings.

A common pattern is for the release owner to say "I don't think there's anything wrong with this change, but we haven't had enough time to test it yet, so it shouldn't go into this release." It helps a lot if the release owner has broad technical knowledge of the project, and can give reasons why the change could be potentially destabilizing (for example, its interactions with other parts of the software, or portability concerns). People will sometimes ask such decisions to be justified, or will argue that a change is not as risky as it looks. These conversations need not be confrontational, as long as the release owner is able to consider all the arguments objectively and not reflexively dig in his heels.

Note that the release owner need not be the same person as the project leader (in cases where there is a project leader at all; see la section intitulée « Benevolent Dictators » in Chapitre 4, Social and Political Infrastructure). In fact, sometimes it's good to make sure they're not the same person. The skills that make a good development leader are not necessarily the same as those that make a good release owner. In something as important as the release process, it may be wise to have someone provide a counterbalance to the project leader's judgement.

Contrast the release owner role with the less dictatorial role described in la section intitulée « Release manager » later in this chapter.

At the opposite extreme from dictatorship by release owner, developers can simply vote on which changes to include in the release. However, since the most important function of release stabilization is to exclude changes, it's important to design the voting system in such a way that getting a change into the release involves positive action by multiple developers. Including a change should need more than just a simple majority (see la section intitulée « Who Votes? » in Chapitre 4, Social and Political Infrastructure). Otherwise, one vote for and none against a given change would suffice to get it into the release, and an unfortunate dynamic would be set up whereby each developer would vote for her own changes, yet would be reluctant to vote against others' changes, for fear of possible retaliation. To avoid this, the system should be arranged such that subgroups of developers must act in cooperation to get any change into the release. This not only means that more people review each change, it also makes any individual developer less hesitant to vote against a change, because she knows that no particular one among those who voted for it would take her vote against as a personal affront. The greater the number of people involved, the more the discussion becomes about the change and less about the individuals.

The system we use in the Subversion project seems to have struck a good balance, so I'll recommend it here. In order for a change to be applied to the release branch, at least three developers must vote in favor of it, and none against. A single "no" vote is enough to stop the change from being included; that is, a "no" vote in a release context is equivalent to a veto (see la section intitulée « Vetoes »). Naturally, any such vote must be accompanied by a justification, and in theory the veto could be overridden if enough people feel it is unreasonable and force a special vote over it. In practice, this has never happened, and I don't expect that it ever will. People are conservative around releases anyway, and when someone feels strongly enough to veto the inclusion of a change, there's usually a good reason for it.

Because the release procedure is deliberately biased toward conservatism, the justifications offered for vetoes are sometimes procedural rather than technical. For example, a person may feel that a change is well-written and unlikely to cause any new bugs, but vote against its inclusion in a micro release simply because it's too big—perhaps it adds a new feature, or in some subtle way fails to fully follow the compatibility guidelines. I've occasionally even seen developers veto something because they simply had a gut feeling that the change needed more testing, even though they couldn't spot any bugs in it by inspection. People grumbled a little bit, but the vetoes stood and the change was not included in the release (I don't remember if any bugs were found in later testing or not, though).

* r2401 (issue #49)
  Prevent client/server handshake from happening twice.
  Justification:
    Avoids extra network turnaround; small change and easy to review.
  Notes:
    This was discussed in http://.../mailing-lists/message-7777.html
    and other messages in that thread.
  Votes:
    +1: jsmith, kimf
    -1: tmartin (breaks compatibility with some pre-1.0 servers;
                 admittedly, those servers are buggy, but why be
                 incompatible if we don't have to?)

* r13222, r13223, r13232
  Rewrite libsvn_fs_fs's auto-merge algorithm
  Justification:
    unacceptable performance (>50 minutes for a small commit) in
    a repository with 300,000 revisions
  Branch:
    1.1.x-r13222@13517
  Votes:
    +1: epg, ghudson

The source code should be shipped in the standard formats for transporting directory trees. For Unix and Unix-like operating systems, the convention is to use TAR format, compressed by compress, gzip, bzip or bzip2. For MS Windows, the standard method for distributing directory trees is zip format, which happens to do compression as well, so there is no need to compress the archive after creating it.

The name of the package should consist of the software's name plus the release number, plus the format suffixes appropriate for the archive type. For example, Scanley 2.5.0, packaged for Unix using GNU Zip (gzip) compression, would look like this:

or for Windows using zip compression:

Either of these archives, when unpacked, should create a single new directory tree named scanley-2.5.0 in the current directory. Underneath the new directory, the source code should be arranged in a layout ready for compilation (if compilation is needed) and installation. In the top level of new directory tree, there should be a plain text README file explaining what the software does and what release this is, and giving pointers to other resources, such as the project's web site, other files of interest, etc. Among those other files should be an INSTALL file, sibling to the README file, giving instructions on how to build and install the software for all the operating systems it supports. As mentioned in la section intitulée « Comment mettre en oeuvre cette licence au projet » in Chapitre 2, Genèse d'un projet, there should also be a COPYING or LICENSE file, giving the software's terms of distribution.

There should also be a CHANGES file (sometimes called NEWS), explaining what's new in this release. The CHANGES file accumulates changelists for all releases, in reverse chronological order, so that the list for this release appears at the top of the file. Completing that list is usually the last thing done on a stabilizing release branch; some projects write the list piecemeal as they're developing, others prefer to save it all up for the end and have one person write it, getting information by combing the version control logs. The list looks something like this:

Version 2.5.0
(20 December 2004, from /branches/2.5.x)
http://svn.scanley.org/repos/svn/tags/2.5.0/

 New features, enhancements:
    * Added regular expression queries (issue #53)
    * Added support for UTF-8 and UTF-16 documents
    * Documentation translated into Polish, Russian, Malagasy
    * ...

 Bugfixes:
    * fixed reindexing bug (issue #945)
    * fixed some query bugs (issues #815, #1007, #1008)
    * ...

The list can be as long as necessary, but don't bother to include every little bugfix and feature enhancement. Its purpose is simply to give users an overview of what they would gain by upgrading to the new release. In fact, the changelist is customarily included in the announcement email (see la section intitulée « Testing and Releasing » later in this chapter), so write it with that audience in mind.

The actual layout of the source code inside the tree should be the same as, or as similar as possible to, the source code layout one would get by checking out the project directly from its version control repository. Usually there are a few differences, for example because the package contains some generated files needed for configuration and compilation (see la section intitulée « Compilation and Installation » later in this chapter), or because it includes third-party software that is not maintained by the project, but that is required and that users are not likely to already have. But even if the distributed tree corresponds exactly to some development tree in the version control repository, the distribution itself should not be a working copy (see Copie de travail ). The release is supposed to represent a static reference point—a particular, unchangeable configuration of source files. If it were a working copy, the danger would be that the user might update it, and afterward think that he still has the release when in fact he has something different.

Remember that the package is the same regardless of the packaging. The release—that is, the precise entity referred to when someone says "Scanley 2.5.0"—is the tree created by unpacking a zip file or tarball. So the project might offer all of these for download:

...but the source tree created by unpacking them must be the same. That source tree is the distribution; the form in which it is downloaded is merely a matter of convenience. Certain trivial differences between source packages are allowable: for example, in the Windows package, text files should have lines ending with CRLF (Carriage Return and Line Feed), while Unix packages should use just LF. The trees may be arranged slightly differently between source packages destined for different operating systems, too, if those operating systems require different sorts of layouts for compilation. However, these are all basically trivial transformations. The basic source files should be the same across all the packagings of a given release.

For software requiring compilation or installation from source, there are usually standard procedures that experienced users expect to be able to follow. For example, for programs written in C, C++, or certain other compiled languages, the standard under Unix-like systems is for the user to type:

   $ ./configure
   $ make
   # make install

The first command autodetects as much about the environment as it can and prepares for the build process, the second command builds the software in place (but does not install it), and the last command installs it on the system. The first two commands are done as a regular user, the third as root. For more details about setting up this system, see the excellent GNU Autoconf, Automake, and Libtool book by Vaughan, Elliston, Tromey, and Taylor. It is published as treeware by New Riders, and its content is also freely available online at http://sources.redhat.com/autobook/.

This is not the only standard, though it is one of the most widespread. The Ant (http://ant.apache.org/) build system is gaining popularity, especially with projects written in Java, and it has its own standard procedures for building and installing. Also, certain programming languages, such as Perl and Python, recommend that the same method be used for most programs written in that language (for example, Perl modules use the command perl Makefile.PL). If it's not obvious to you what the applicable standards are for your project, ask an experienced developer; you can safely assume that some standard applies, even if you don't know what it is at first.

Whatever the appropriate standards for you project are, don't deviate from them unless you absolutely must. Standard installation procedures are practically spinal reflexes for a lot of system administrators now. If they see familiar invocations documented in your project's INSTALL file, that instantly raises their faith that your project is generally aware of conventions, and that it is likely to have gotten other things right as well. Also, as discussed in la section intitulée « Téléchargements » in Chapitre 2, Genèse d'un projet, having a standard build procedure pleases potential developers.

On Windows, the standards for building and installing are a bit less settled. For projects requiring compilation, the general convention seems to be to ship a tree that can fit into the workspace/project model of the standard Microsoft development environments (Developer Studio, Visual Studio, VS.NET, MSVC++, etc.). Depending on the nature of your software, it may be possible to offer a Unix-like build option on Windows via the Cygwin (http://www.cygwin.com/) environment. And of course, if you're using a language or programming framework that comes with its own build and install conventions—e.g., Perl or Python—you should simply use whatever the standard method is for that framework, whether on Windows, Unix, Mac OS X, or any other operating system.

Be willing to put in a lot of extra effort in order to make your project conform to the relevant build or installation standards. Building and installing is an entry point: it's okay for things to get harder after that, if they absolutely must, but it would be a shame for the user's or developer's very first interaction with the software to require unexpected steps.

Although the formal release is a source code package, most users will install from binary packages, either provided by their operating system's software distribution mechanism, or obtained manually from the project web site or from some third party. Here "binary" doesn't necessarily mean "compiled"; it just means any pre-configured form of the package that allows a user to install it on his computer without going through the usual source-based build and install procedures. On RedHat GNU/Linux, it is the RPM system; on Debian GNU/Linux, it is the APT (.deb) system; on MS Windows, it's usually .MSI files or self-installing .exe files.

Whether these binary packages are assembled by people closely associated with the project, or by distant third parties, users are going to treat them as equivalent to the project's official releases, and will file issues in the project's bug tracker based on the behavior of the binary packages. Therefore, it is in the project's interest to provide packagers with clear guidelines, and work closely with them to see to it that what they produce represents the software fairly and accurately.

The main thing packagers need to know is that they should always base their binary packages on an official source release. Sometimes packagers are tempted to pull a later incarnation of the code from the repository, or include selected changes that were committed after the release was made, in order to provide users with certain bug fixes or other improvements. The packager thinks he is doing his users a favor by giving them the more recent code, but actually this practice can cause a great deal of confusion. Projects are prepared to receive reports of bugs found in released versions, and bugs found in recent trunk and major branch code (that is, found by people who deliberately run bleeding edge code). When a bug report comes in from these sources, the responder will often be able to confirm that the bug is known to be present in that snapshot, and perhaps that it has since been fixed and that the user should upgrade or wait for the next release. If it is a previously unknown bug, having the precise release makes it easier to reproduce and easier to categorize in the tracker.

Projects are not prepared, however, to receive bug reports based on unspecified intermediate or hybrid versions. Such bugs can be hard to reproduce; also, they may be due to unexpected interactions in isolated changes pulled in from later development, and thereby cause misbehaviors that the project's developers should not have to take the blame for. I have even seen dismayingly large amounts of time wasted because a bug was absent when it should have been present: someone was running a slightly patched up version, based on (but not identical to) an official release, and when the predicted bug did not happen, everyone had to dig around a lot to figure out why.

Still, there will sometimes be circumstances when a packager insists that modifications to the source release are necessary. Packagers should be encouraged to bring this up with the project's developers and describe their plans. They may get approval, but failing that, they will at least have notified the project of their intentions, so the project can watch out for unusual bug reports. The developers may respond by putting a disclaimer on the project's web site, and may ask that the packager do the same thing in the appropriate place, so that users of that binary package know what they are getting is not exactly the same as what the project officially released. There need be no animosity in such a situation, though unfortunately there often is. It's just that packagers have a slightly different set of goals from developers. The packagers mainly want the best out-of-the-box experience for their users. The developers want that too, of course, but they also need to ensure that they know what versions of the software are out there, so they can receive coherent bug reports and make compatibility guarantees. Sometimes these goals conflict. When they do, it's good to keep in mind that the project has no control over the packagers, and that the bonds of obligation run both ways. It's true that the project is doing the packagers a favor simply by producing the software. But the packagers are also doing the project a favor, by taking on a mostly unglamorous job in order to make the software more widely available, often by orders of magnitude. It's fine to disagree with packagers, but don't flame them; just try to work things out as best you can.

For important releases containing many changes, many projects prefer to put out release candidates first, e.g., scanley-2.5.0-beta1 before scanley-2.5.0. The purpose of a candidate is to subject the code to wide testing before blessing it as an official release. If problems are found, they are fixed on the release branch and a new candidate release is rolled out (scanley-2.5.0-beta2). The cycle continues until no unacceptable bugs are left, at which point the last candidate release becomes the official release—that is, the only difference between the last candidate release and the real release is the removal of the qualifier from the version number.

In most other respects, a candidate release should be treated the same as a real release. The alpha, beta, or rc qualifier is enough to warn conservative users to wait until the real release, and of course the announcement emails for the candidate releases should point out that their purpose is to solicit feedback. Other than that, give candidate releases the same amount of care as regular releases. After all, you want people to use the candidates, because exposure is the best way to uncover bugs, and also because you never know which candidate release will end up becoming the official release.

Announcing a release is like announcing any other event, and should use the procedures described in la section intitulée « Publicity » in Chapitre 6, Communications. There are a few specific things to do for releases, though.

Whenever you give the URL to the downloadable release tarball, make sure to also give the MD5/SHA1 checksums and pointers to the digital signatures file. Since the announcement happens in multiple forums (mailing list, news page, etc.), this means users can get the checksums from multiple sources, which gives the most security-conscious among them extra assurance that the checksums themselves have not been tampered with. Giving the link to the digital signature files multiple times doesn't make those signatures more secure, but it does reassure people (especially those who don't follow the project closely) that the project takes security seriously.

In the announcement email, and on news pages that contain more than just a blurb about the release, make sure to include the relevant portion of the CHANGES file, so people can see why it might be in their interests to upgrade. This is as important with candidate releases as with final releases; the presence of bugfixes and new features is important in tempting people to try out a candidate release.

Finally, don't forget to thank the development team, the testers, and all the people who took the time to file good bug reports. Don't single out anyone by name, though, unless there's someone who is individually responsible for a huge piece of work, the value of which is widely recognized by everyone in the project. Just be wary of sliding down the slippery slope of credit inflation (see la section intitulée « Credit » in Chapitre 8, Managing Volunteers).

Most of the details of handling security bugs were covered in la section intitulée « Announcing Security Vulnerabilities » in Chapitre 6, Communications, but there are some special details to discuss for doing security releases.

A security release is a release made solely to close a security vulnerability. The code that fixes the bug cannot be made public until the release is available, which means not only that the fixes cannot be committed to the repository until the day of the release, but also that the release cannot be publicly tested before it goes out the door. Obviously, the developers can examine the fix among themselves, and test the release privately, but widespread real-world testing is not possible.

Because of this lack of testing, a security release should always consist of some existing release plus the fixes for the security bug, with no other changes. This is because the more changes you ship without testing, the more likely that one of them will cause a new bug, perhaps even a new security bug! This conservatism is also friendly to administrators who may need to deploy the security fix, but whose upgrade policy prefers that they not deploy any other changes at the same time.

Making a security release sometimes involves some minor deception. For example, the project may have been working on a 1.1.3 release, with certain bug fixes to 1.1.2 already publicly declared, when a security report comes in. Naturally, the developers cannot talk about the security problem until they make the fix available; until then, they must continue to talk publicly as though 1.1.3 will be what it's always been planned to be. But when 1.1.3 actually comes out, it will differ from 1.1.2 only in the security fixes, and all those other fixes will have been deferred to 1.1.4 (which, of course, will now also contain the security fix, as will all other future releases).

You could add an extra component to an existing release to indicate that it contains security changes only. For example, people would be able to tell just from the numbers that 1.1.2.1 is a security release against 1.1.2, and they would know that any release "higher" than that (e.g., 1.1.3, 1.2.0, etc.) contains the same security fixes. For those in the know, this system conveys a lot of information. On the other hand, for those not following the project closely, it can be a bit confusing to see a three-component release number most of the time with an occasional four-component one thrown in seemingly at random. Most projects I've looked at choose consistency and simply use the next regularly scheduled number for security releases, even when it means shifting other planned releases by one.

One area where open source projects have historically differed from proprietary projects is in release planning. Proprietary projects usually have firmer deadlines. Sometimes it's because customers were promised that an upgrade would be available by a certain date, because the new release needs to be coordinated with some other effort for marketing purposes, or because the venture capitalists who invested in the whole thing need to see some results before they put in any more funding. Free software projects, on the other hand, were until recently mostly motivated by amateurism in the most literal sense: they were written for the love of it. No one felt the need to ship before all the features were ready, and why should they? It wasn't as if anyone's job was on the line.

Nowadays, many open source projects are funded by corporations, and are correspondingly more and more influenced by deadline-conscious corporate culture. This is in many ways a good thing, but it can cause conflicts between the priorities of those developers who are being paid and those who are volunteering their time. These conflicts often happen around the issue of when and how to schedule releases. The salaried developers who are under pressure will naturally want to just pick a date when the releases will occur, and have everyone's activities fall into line. But the volunteers may have other agendas—perhaps features they want to complete, or some testing they want to have done—that they feel the release should wait on.

There is no general solution to this problem except discussion and compromise, of course. But you can minimize the frequency and degree of friction caused, by decoupling the proposed existence of a given release from the date when it would go out the door. That is, try to steer discussion toward the subject of which releases the project will be making in the near- to medium-term future, and what features will be in them, without at first mentioning anything about dates, except for rough guesses with wide margins of error. By nailing down feature sets early, you reduce the complexity of the discussion centered on any individual release, and therefore improve predictability. This also creates a kind of inertial bias against anyone who proposes to expand the definition of a release by adding new features or other complications. If the release's contents are fairly well defined, the onus is on the proposer to justify the expansion, even though the date of the release may not have been set yet.

In his multi-volume biography of Thomas Jefferson, Jefferson and His Time, Dumas Malone tells the story of how Jefferson handled the first meeting held to decide the organization of the future University of Virginia. The University had been Jefferson's idea in the first place, but (as is the case everywhere, not just in open source projects) many other parties had climbed on board quickly, each with their own interests and agendas. When they gathered at that first meeting to hash things out, Jefferson made sure to show up with meticulously prepared architectural drawings, detailed budgets for construction and operation, a proposed curriculum, and the names of specific faculty he wanted to import from Europe. No one else in the room was even remotely as prepared; the group essentially had to capitulate to Jefferson's vision, and the University was eventually founded more or less in accordance with his plans. The facts that construction went far over budget, and that many of his ideas did not, for various reasons, work out in the end, were all things Jefferson probably knew perfectly well would happen. His purpose was strategic: to show up at the meeting with something so substantive that everyone else would have to fall into the role of simply proposing modifications to it, so that the overall shape, and therefore schedule, of the project would be roughly as he wanted.

In the case of a free software project, there is no single "meeting", but instead a series of small proposals made mostly by means of the issue tracker. But if you have some credibility in the project to start with, and you start assigning various features, enhancements, and bugs to target releases in the issue tracker, according to some announced overall plan, people will mostly go along with you. Once you've got things laid out more or less as you want them, the conversations about actual release dates will go much more smoothly.

It is crucial, of course, to never present any individual decision as written in stone. In the comments associated with each assignment of an issue to a specific future release, invite discussion, dissent, and be genuinely willing to be persuaded whenever possible. Never exercise control merely for the sake of exercising control: the more deeply others participate in the release planning process (see la section intitulée « Share Management Tasks as Well as Technical Tasks » in Chapitre 8, Managing Volunteers), the easier it will be to persuade them to share your priorities on the issues that really count for you.

The other way the project can lower tensions around release planning is to make releases fairly often. When there's a long time between releases, the importance of any individual release is magnified in everyone's minds; people are that much more crushed when their code doesn't make it in, because they know how long it might be until the next chance. Depending on the complexity of the release process and the nature of your project, somewhere between every three and six months is usually about the right gap between releases, though maintenance lines may put out micro releases a bit faster, if there is demand for them.

Delegation is not merely a way to spread the workload around; it is also a political and social tool. Consider all the effects when you ask someone to do something. The most obvious effect is that, if he accepts, he does the task and you don't. But another effect is that he is made aware that you trusted him to handle the task. Furthermore, if you made the request in a public forum, then he knows that others in the group have been made aware of that trust too. He may also feel some pressure to accept, which means you must ask in a way that allows him to decline gracefully if he doesn't really want the job. If the task requires coordination with others in the project, you are effectively proposing that he become more involved, form bonds that might not otherwise have been formed, and perhaps become a source of authority in some subdomain of the project. The added involvement may be daunting, or it may lead him to become engaged in other ways as well, from an increased feeling of overall commitment.

Because of all these effects, it often makes sense to ask someone else to do something even when you know you could do it faster or better yourself. Of course, there is sometimes a strict economic efficiency argument for this anyway: perhaps the opportunity cost of doing it yourself would be too high—there might be something even more important you could do with that time. But even when the opportunity cost argument doesn't apply, you may still want to ask someone else to take on the task, because in the long run you want to draw that person deeper into the project, even if it means spending extra time watching over them at first. The converse technique also applies: if you occasionally volunteer for work that someone else doesn't want or have time to do, you will gain his good will and respect. Delegation and substitution are not just about getting individual tasks done; they're also about drawing people into a closer committment to the project.

Praise and criticism are not opposites; in many ways, they are very similar. Both are primarily forms of attention, and are most effective when specific rather than generic. Both should be deployed with concrete goals in mind. Both can be diluted by inflation: praise too much or too often and you will devalue your praise; the same is true for criticism, though in practice, criticism is usually reactive and therefore a bit more resistant to devaluation.

An important feature of technical culture is that detailed, dispassionate criticism is often taken as a kind of praise (as discussed in la section intitulée « Recognizing Rudeness » in Chapitre 6, Communications), because of the implication that the recipient's work is worth the time required to analyze it. However, both of those conditions—detailed and dispassionate—must be met for this to be true. For example, if someone makes a sloppy change to the code, it is useless (and actually harmful) to follow up saying simply "That was sloppy." Sloppiness is ultimately a characteristic of a person, not of their work, and it's important to keep your reactions focused on the work. It's much more effective to describe all the things wrong with the change, tactfully and without malice. If this is the third or fourth careless change in a row by the same person, it's appropriate to say that—again without anger—at the end of your critique, to make it clear that the pattern has been noticed.

If someone does not improve in response to criticism, the solution is not more or stronger criticism. The solution is for the group to remove that person from the position of incompetence, in a way that minimizes hurt feelings as much as possible; see la section intitulée « Transitions » later in this chapter for examples. That is a rare occurrence, however. Most people respond pretty well to criticism that is specific, detailed, and contains a clear (even if unspoken) expectation of improvement.

Praise won't hurt anyone's feelings, of course, but that doesn't mean it should be used any less carefully than criticism. Praise is a tool: before you use it, ask yourself why you want to use it. As a rule, it's not a good idea to praise people for doing what they usually do, or for actions that are a normal and expected part of participating in the group. If you were to do that, it would be hard to know when to stop: should you praise everyone for doing the usual things? After all, if you leave some people out, they'll wonder why. It's much better to express praise and gratitude sparingly, in response to unusual or unexpected efforts, with the intention of encouraging more such efforts. When a participant seems to have moved permanently into a state of higher productivity, adjust your praise threshold for that person accordingly. Repeated praise for normal behavior gradually becomes meaningless anyway. Instead, that person should sense that her high level of productivity is now considered normal and natural, and only work that goes beyond that should be specially noticed.

This is not to say that the person's contributions shouldn't be acknowledged, of course. But remember that if the project is set up right, everything that person does is already visible anyway, and so the group will know (and the person will know that the rest of the group knows) everything she does. There are also ways to acknowledge someone's work by means other than direct praise. You could mention in passing, while discussing a related topic, that she has done a lot of work in the given area and is the resident expert there; you could publicly consult her on some question about the code; or perhaps most effectively, you could conspicuously make further use of the work she has done, so she sees that others are now comfortable relying on the results of her work. It's probably not necessary to do these things in any calculated way. Someone who regularly makes large contributions in a project will know it, and will occupy a position of influence by default. There's usually no need to take explicit steps to ensure this, unless you sense that, for whatever reason, a contributor is underappreciated.

Watch out for participants who try to stake out exclusive ownership of certain areas of the project, and who seem to want to do all the work in those areas, to the extent of aggressively taking over work that others start. Such behavior may even seem healthy at first. After all, on the surface it looks like the person is taking on more responsibility, and showing increased activity within a given area. But in the long run, it is destructive. When people sense a "no trespassing" sign, they stay away. This results in reduced review in that area, and greater fragility, because the lone developer becomes a single point of failure. Worse, it fractures the cooperative, egalitarian spirit of the project. The theory should always be that any developer is welcome to help out on any task at any time. Of course, in practice things work a bit differently: people do have areas where they are more and less influential, and non-experts frequently defer to experts in certain domains of the project. But the key is that this is all voluntary: informal authority is granted based on competence and proven judgement, but it should never be actively taken. Even if the person desiring the authority really is competent, it is still crucial that she hold that authority informally, through the consensus of the group, and that the authority never cause her to exclude others from working in that area.

Rejecting or editing someone's work for technical reasons is an entirely different matter, of course. There, the decisive factor is the content of the work, not who happened to act as gatekeeper. It may be that the same person happens to do most of the reviewing for a given area, but as long as he never tries to prevent someone else from doing that work too, things are probably okay.

In order to combat incipient territorialism, or even the appearance of it, many projects have taken the step of banning the inclusion of author names or designated maintainer names in source files. I wholeheartedly agree with this practice: we follow it in the Subversion project, and it is more or less official policy at the Apache Software Foundation. ASF member Sander Striker puts it this way:

A software project's source code files are the core of its identity. They should reflect the fact that the developer community as a whole is responsible for them, and not be divided up into little fiefdoms.

People sometimes argue in favor of author or maintainer tags in source files on the grounds that this gives visible credit to those who have done the most work there. There are two problems with this argument. First, the tags inevitably raise the awkward question of how much work one must do to get one's own name listed there too. Second, they conflate the issue of credit with that of authority: having done work in the past does not imply ownership of the area where the work was done, but it's difficult if not impossible to avoid such an implication when individual names are listed at the tops of source files. In any case, credit information can already be obtained from the version control logs and other out-of-band mechanisms like mailing list archives, so no information is lost by banning it from the source files themselves.

If your project decides to ban individual names from source files, make sure not to go overboard. For instance, many projects have a contrib/ area where small tools and helper scripts are kept, often written by people who are otherwise not associated with the project. It's fine for those files to contain author names, because they are not really maintained by the project as a whole. On the other hand, if a contributed tool starts getting hacked on by other people in the project, eventually you may want to move it to a less isolated location and, assuming the original author approves, remove the author's name, so that the code looks like any other community-maintained resource. If the author is sensitive about this, compromise solutions are acceptable, for example:

But it's better to avoid such compromises, if possible, and most authors are willing to be persuaded, because they're happy that their contribution is being made a more integral part of the project.

The important thing is to remember that there is a continuum between the core and the periphery of any project. The main source code files for the software are clearly part of the core, and should be considered as maintained by the community. On the other hand, companion tools or pieces of documentation may be the work of single individuals, who maintain them essentially alone, even though the works may be associated with, and even distributed with, the project. There is no need to apply a one-size-fits-all rule to every file, as long as the principle that community-maintained resources are not allowed to become individual territories is upheld.

Try not to let humans do what machines could do instead. As a rule of thumb, automating a common task is worth at least ten times the effort a developer would spend doing that task manually one time. For very frequent or very complex tasks, that ratio could easily go up to twenty or even higher.

Thinking of yourself as a "project manager", rather than just another developer, may be a useful attitude here. Sometimes individual developers are too wrapped up in low-level work to see the big picture and realize that everyone is wasting a lot of effort performing automatable tasks manually. Even those who do realize it may not take the time to solve the problem: because each individual performance of the task does not feel like a huge burden, no one ever gets annoyed enough to do anything about it. What makes automation compelling is that that small burden is multiplied by the number of times each developer incurs it, and then that number is multiplied by the number of developers.

Here, I am using the term "automation" broadly, to mean not only repeated actions where one or two variables change each time, but any sort of technical infrastructure that assists humans. The minimum standard automation required to run a project these days was described in Chapitre 3, L'infrastructure technique, but each project may have its own special problems too. For example, a group working on documentation might want to have a web site displaying the most up-to-date versions of the documents at all times. Since documentation is often written in a markup language like XML, there may be a compilation step, often quite intricate, involved in creating displayable or downloadable documents. Arranging a web site where such compilation happens automatically on every commit can be complicated and time-consuming—but it is worth it, even if it costs you a day or more to set up. The overall benefits of having up-to-date pages available at all times are huge, even though the cost of not having them might seem like only a small annoyance at any single moment, to any single developer.

Taking such steps eliminates not merely wasted time, but the griping and frustration that ensue when humans make missteps (as they inevitably will) in trying to perform complicated procedures manually. Multi-step, deterministic operations are exactly what computers were invented for; save your humans for more interesting things.

Each interaction with a user is an opportunity to get a new volunteer. When a user takes the time to post to one of the project's mailing lists, or to file a bug report, he has already tagged himself as having more potential for involvement than most users (from whom the project will never hear at all). Follow up on that potential: if he described a bug, thank him for the report and ask him if he wants to try fixing it. If he wrote to say that an important question was missing from the FAQ, or that the program's documentation was deficient in some way, then freely acknowledge the problem (assuming it really exists) and ask if he's interested in writing the missing material himself. Naturally, much of the time the user will demur. But it doesn't cost much to ask, and every time you do, it reminds the other listeners in that forum that getting involved in the project is something anyone can do.

Don't limit your goals to acquiring new developers and documentation writers. For example, even training people to write good bug reports pays off in the long run, if you don't spend too much time per person, and if they go on to submit more bug reports in the future—which they are more likely to do if they got a constructive reaction to their first report. A constructive reaction need not be a fix for the bug, although that's always the ideal; it can also be a solicitation for more information, or even just a confirmation that the behavior is a bug. People want to be listened to. Secondarily, they want their bugs fixed. You may not always be able to give them the latter in a timely fashion, but you (or rather, the project as a whole) can give them the former.

A corollary of this is that developers should not express anger at people who file well-intended but vague bug reports. This is one of my personal pet peeves; I see developers do it all the time on various open source mailing lists, and the harm it does is palpable. Some hapless newbie will post a useless report:

Some developer—who has seen this kind of report a thousand times, and hasn't stopped to think that the newbie has not—will respond like this:

This developer has failed to see things from the user's point of view, and also failed to consider the effect such a reaction might have on all the other people watching the exchange. Naturally a user who has no programming experience, and no prior experience reporting bugs, will not know how to write a bug report. What is the right way to handle such a person? Educate them! And do it in such a way that they come back for more:

This way of responding is far more effective at extracting the needed information from the user, because it is written to the user's point of view. First, it expresses sympathy: You had a problem; we feel your pain. (This is not necessary in every bug report response; it depends on the severity of the problem and how upset the user seemed.) Second, instead of belittling her for not knowing how to report a bug, it tells her how, and in enough detail to be actually useful—for example, many users don't realize that "show us the error" means "show us the exact text of the error, with no omissions or abridgements." The first time you work with such a user, you need to be specific about that. Finally, it offers a pointer to much more detailed and complete instructions for reporting bugs. If you have successfully engaged with the user, she will often take the time to read that document and do what it says. This means, of course, that you have to have the document prepared in advance. It should give clear instructions about what kind of information your development team wants to see in every bug report. Ideally, it should also evolve over time in response to the particular sorts of omissions and misreports users tend to make for your project.

The Subversion project's bug reporting instructions are a fairly standard example of the form (see Annexe D, Example Instructions for Reporting Bugs). Notice how they close with an invitation to provide a patch to fix the bug. This is not because such an invitation will lead to a greater patch/report ratio—most users who are capable of fixing bugs already know that a patch would be welcome, and don't need to be told. The invitation's real purpose is to emphasize to all readers, especially those new to the project or new to free software in general, that the project runs on volunteer contributions. In a sense, the project's current developers are no more responsible for fixing the bug than is the person who reported it. This is an important point that many new users will not be familiar with. Once they realize it, they're more likely to help make the fix happen, if not by contributing code then by providing a more thorough reproduction recipe, or by offering to test fixes that other people post. The goal is to make every user realize that there is no innate difference between herself and the people who work on the project—that it's a question of how much time and effort one puts in, not a question of who one is.

The admonition against responding angrily does not apply to rude users. Occasionally people post bug reports or complaints that, regardless of their informational content, show a sneering contempt at the project for some failing. Often such people are alternately insulting and flattering, such as the person who posted this to a Subversion mailing list:

Initial response to this rather inflammatory post was surprisingly restrained: people pointed out that the project had a published policy of not providing official binaries, and said, with varying degrees of annoyance, that he ought to volunteer to produce them himself if they were so important to him. Believe it or not, his next post started with these lines:

...and then he went on to berate the project again for not providing binaries, while still not volunteering to do anything about it. After that, about 50 people just jumped all over him, and I can't say I really minded. The "zero-tolerance" policy toward rudeness advocated in la section intitulée « Tuez l'agressivité dans l'oeuf » in Chapitre 2, Genèse d'un projet applies to people with whom the project has (or would like to have) a sustained interaction. But when someone makes it clear from the start that he is going to be a fountain of bile, there is no point making him feel welcome.

Such situations are fortunately quite rare, and they are noticeably rarer in projects that make an effort to engage users constructively and courteously from their very first interaction.

In a free software project that receives a lot of patches, keeping track of which patches have arrived and what has been decided about them can be a nightmare, especially if done in a decentralized way. Most patches arrive as posts to the project's development mailing list (though some may appear first in the issue tracker, or on external web sites), and there are a number of different routes a patch can take after arrival.

Sometimes someone reviews the patch, finds problems, and bounces it back to the original author for cleanup. This usually leads to an iterative process—all visible on the mailing list—in which the original author posts revised versions of the patch until the reviewer has nothing more to criticize. It is not always easy to tell when this process is done: if the reviewer commits the patch, then clearly the cycle is complete. But if she does not, it might be because she simply didn't have time, or doesn't have commit access herself and couldn't rope any of the other developers into doing it.

Another frequent response to a patch is a freewheeling discussion, not necessarily about the patch itself, but about whether the concept behind the patch is good. For example, the patch may fix a bug, but the project prefers to fix that bug in another way, as part of solving a more general class of problems. Often this is not known in advance, and it is the patch that stimulates the discovery.

Occasionally, a posted patch is met with utter silence. Usually this is due to no developer having time at that moment to review the patch, so each hopes that someone else will do it. Since there's no particular limit to how long each person waits for someone else to pick up the ball, and meanwhile other priorities are always coming up, it's very easy for a patch to slip through the cracks without any single person intending for that to happen. The project might miss out on a useful patch this way, and there are other harmful side effects as well: it is discouraging to the author, who invested work in the patch, and it makes the project as a whole look a bit out of touch, especially to others considering writing patches.

The patch manager's job is to make sure that patches don't "slip through the cracks." This is done by following every patch through to some sort of stable state. The patch manager watches every mailing list thread that results from a patch posting. If it ends in a commit of the patch, he does nothing. If it goes into a review/revise iteration, ending with a final version of the patch but no commit, he files an issue pointing to the final version, and to the mailing list thread around it, so that there is a permanent record for developers to follow up on later. If the patch addresses an existing issue, he annotates that issue with the relevant information, instead of opening a new issue.

When a patch gets no reaction at all, the patch manager waits a few days, then follows up asking if anyone is going to review it. This usually gets a reaction: a developer may explain that she doesn't think the patch should be applied, and give the reasons why, or she may review it, in which case one of the previously described paths is taken. If there is still no response, the patch manager may or may not file an issue for the patch, at his discretion, but at least the original submitter got some reaction.

Having a patch manager has saved the Subversion development team a lot of time and mental energy. Without a designated person to take responsibility, every developer would constantly have to worry "If I don't have time to respond to this patch right now, can I count on someone else doing it? Should I try to keep an eye on it? But if other people are also keeping an eye on it, for the same reasons, then we'd have needlessly duplicated effort." The patch manager removes the second-guessing from the situation. Each developer can make the decision that is right for her at the moment she first sees the patch. If she wants to follow up with a review, she can do that—the patch manager will adjust his behavior accordingly. If she wants to ignore the patch completely, that's fine too; the patch manager will make sure it isn't forgotten.

Because this system works only if people can depend on the patch manager being there without fail, the role should be held formally. In Subversion, we advertised for it on the development and users mailing lists, got several volunteers, and took the first one who replied. When that person had to step down (see la section intitulée « Transitions » later in this chapter), we did the same thing again. We've never tried having multiple people share the role, because of the communications overhead that would be required between them; but perhaps at very high volumes of patch submission, a multiheaded patch manager might make sense.

In software projects, "translation" can refer to two very different things. It can mean translating the software's documentation into other languages, or it can mean translating the software itself—that is, having the program display errors and help messages in the user's preferred language. Both are complex tasks, but once the right infrastructure is in place, they are largely separable from other development. Because the tasks are similar in some ways, it may make sense (depending on your project) to have a single translation manager handle both, or it may be better to have two different managers.

In the Subversion project, we have one translation manager handle both. He does not actually write the translations himself, of course—he may help out on one or two, but as of this writing, he would need to speak ten languages (twelve counting dialects) in order to work on all of them! Instead, he manages teams of volunteer translators: he helps them coordinate among each other, and he coordinates between the teams and the rest of the project.

Part of the reason the translation manager is necessary is that translators are a different demographic from developers. They sometimes have little or no experience working in a version control repository, or indeed with working as part of a distributed volunteer team at all. But in other respects they are often the best kind of volunteer: people with specific domain knowledge who saw a need and chose to get involved. They are usually willing to learn, and enthusiastic to get to work. All they need is someone to tell them how. The translation manager makes sure that the translations happen in a way that does not interfere unnecessarily with regular development. He also serves as a sort of representative of the translators as a unified body, whenever the developers must be informed of technical changes required to support the translation effort.

Thus, the position's most important skills are diplomatic, not technical. For example, in Subversion we have a policy that all translations should have at least two people working on them, because otherwise there is no way for the text to be reviewed. When a new volunteer shows up offering to translate Subversion to, say, Malagasy, the translation manager has to either hook him up with someone who posted six months ago expressing interest in doing a Malagasy translation, or else politely ask the volunteer to go find another Malagasy translator to work with as a partner. Once enough people are available, the manager sets them up with the proper kind of commit access, informs them of the project's conventions (such as how to write log messages), and then keeps an eye out to make sure they adhere to those conventions.

Conversations between the translation manager and the developers, or between the translation manager and translation teams, are usually held in the project's original language—that is, the language from which all the translations are being made. For most free software projects, this is English, but it doesn't matter what it is as long as the project agrees on it. (English is probably best for projects that want to attract a broad international development community, though.)

Conversations within a particular translation team usually happen in their shared language, however, and one of the other tasks of the translation manager is to set up a dedicated mailing list for each team. That way the translators can discuss their work freely, without distracting people on the project's main lists, most of whom would not be able to understand the translation language anyway.

Keeping software documentation up-to-date is a never-ending task. Every new feature or enhancement that goes into the code has the potential to cause a change in the documentation. Also, once the project's documentation reaches a certain level of completeness, you will find that a lot of the patches people send in are for the documentation, not for the code. This is because there are many more people competent to fix bugs in prose than in code: all users are readers, but only a few are programmers.

Documentation patches are usually much easier to review and apply than code patches. There is little or no testing to be done, and the quality of the change can be evaluated quickly just by review. Since the quantity is high, but the review burden fairly low, the ratio of administrative overhead to productive work is greater for documentation patches than for code patches. Furthermore, most of the patches will probably need some sort of adjustment, in order to maintain a consistent authorial voice in the documentation. In many cases, patches will overlap with or affect other patches, and need to be adjusted with respect to each other before being committed.

Given the exigencies of handling documentation patches, and the fact that the code base needs to be constantly monitored so the documentation can be kept up-to-date, it makes sense to have one person, or a small team, dedicated to the task. They can keep a record of exactly where and how the documentation lags behind the software, and they can have practiced procedures for handling large quantities of patches in an integrated way.

Of course, this does not preclude other people in the project from applying documentation patches on the fly, especially small ones, as time permits. And the same patch manager (see la section intitulée « Patch Manager » earlier in this chapter) can track both code and documentation patches, filing them wherever the development and documentation teams want them, respectively. (If the total quantity of patches ever exceeds one human's capacity to track, though, switching to separate patch managers for code and documentation is probably a good first step.) The point of a documentation team is to have people who think of themselves as responsible for keeping the documentation organized, up-to-date, and consistent with itself. In practice, this means knowing the documentation intimately, watching the code base, watching the changes others commit to the documentation, watching for incoming documentation patches, and using all these information sources to do whatever is necessary to keep the documentation healthy.

The number of issues in a project's bug tracker grows in proportion to the number of people using the software. Therefore, even as you fix bugs and ship an increasingly robust program, you should still expect the number of open issues to grow essentially without bound. The frequency of duplicate issues will also increase, as will the frequency of incomplete or poorly described issues.

Issue managers help alleviate these problems by watching what goes into the database, and periodically sweeping through it looking for specific problems. Their most common action is probably to fix up incoming issues, either because the reporter didn't set some of the form fields correctly, or because the issue is a duplicate of one already in the database. Obviously, the more familiar an issue manager is with the project's bug database, the more efficiently she will be able to detect duplicate issues—this is one of the main advantages of having a few people specialize in the bug database, instead of everyone trying to do it ad hoc. When the group tries to do it in a decentralized manner, no single individual acquires a deep expertise in the content of the database.

Issue managers can also help map between issues and individual developers. When there are a lot of bug reports coming in, not every developer may read the issue notification mailing list with equal attention. However, if someone who knows the development team is keeping an eye on all incoming issues, then she can discreetly direct certain developers' attention to specific bugs when appropriate. Of course, this has to be done with a sensitivity to everything else going on in development, and to the recipient's desires and temperament. Therefore, it is often best for issue managers to be developers themselves.

Depending on how your project uses the issue tracker, issue managers can also shape the database to reflect the project's priorities. For example, in Subversion we schedule issues into specific future releases, so that when someone asks "When will bug X be fixed?" we can say "Two releases from now," even if we can't give an exact date. The releases are represented in the issue tracker as target milestones, a field available in IssueZilla.^[22] As a rule, every Subversion release has one major new feature and a list of specific bug fixes. We assign the appropriate target milestone to all the issues planned for that release (including the new feature—it gets an issue too), so that people can view the bug database through the lens of release scheduling. These targets rarely remain static, however. As new bugs come in, priorities sometimes get shifted around, and issues must be moved from one milestone to another so that each release remains manageable. This, again, is best done by people who have an overall sense of what's in the database, and how various issues relate to each other.

Another thing issue managers do is notice when issues become obsolete. Sometimes a bug is fixed accidentally as part of an unrelated change to the software, or sometimes the project changes its mind about whether a certain behavior is buggy. Finding obsoleted issues is not easy: the only way to do it systematically is by making a sweep over all the issues in the database. Full sweeps become less and less feasible over time, however, as the number of issues grows. After a certain point, the only way to keep the database sane is to use a divide-and-conquer approach: categorize issues immediately on arrival and direct them to the appropriate developer's or team's attention. The recipient then takes charge of the issue for the rest of its lifetime, shepherding it to resolution or oblivion as necessary. When the database is that large, the issue manager becomes more of an overall coordinator, spending less time looking at each issue herself and more time getting it into the right person's hands.

FAQ maintenance is a surprisingly difficult problem. Unlike most other documents in a project, whose content is planned out in advance by the authors, a FAQ is a wholly reactive document (see Maintenir une FAQ). No matter how big it gets, you still never know what the next addition will be. And because it is always added to piecemeal, it is very easy for the document as a whole to become incoherent and disorganized, and even to contain duplicate or semi-duplicate entries. Even when it does not have any obvious problems like that, there are often unnoticed interdependencies between items—links that should be made but aren't—because the related items were added a year apart.

The role of a FAQ manager is twofold. First, she maintains the overall quality of the FAQ by staying familiar with at least the topics of all the questions in it, so that when people add new items that are duplicates of, or related to, existing items, the appropriate adjustments can be made. Second, she watches the project mailing lists and other forums for recurring problems or questions, and to write new FAQ entries based on this input. This latter task can be quite complex: one must be able to follow a thread, recognize the core questions raised in it, post a proposed FAQ entry, incorporate comments from others (since it's impossible for the FAQ manager to be an expert in every topic covered by the FAQ), and sense when the process is finished so the item can at last be added.

The FAQ manager usually also becomes the default expert in FAQ formatting. There are a lot of little details involved in keeping a FAQ in shape (see la section intitulée « Treat all resources like archives » in Chapitre 6, Communications); when random people edit the FAQ, they will sometimes forget some of these details. That's okay, as long as the FAQ manager is there to clean up after them.

Various free software is available to help with the process of FAQ maintenance. It's fine to use it, as long as it doesn't compromise the quality of the FAQ, but beware of over-automation. Some projects try to fully automate the process of FAQ maintenance, allowing everyone to contribute and edit FAQ items in a manner similar to a wiki (see la section intitulée « Wikis » in Chapitre 3, L'infrastructure technique). I've seen this happen particularly with Faq-O-Matic (http://faqomatic.sourceforge.net/), though it may be that the cases I saw were simply abuses that went beyond what Faq-O-Matic was originally intended for. In any case, while complete decentralization of FAQ maintenance does reduce the workload for the project, it also results in a poorer FAQ. There's no one person with a broad view of the entire FAQ, no one to notice when certain items need updating or become obsolete entirely, and no one keeping watch for interdependencies between items. The result is a FAQ that often fails to provide users what they were looking for, and in the worst cases misleads them. Use whatever tools you need to to maintain your project's FAQ, but never let the convenience of the tools seduce you into compromising the quality of the FAQ.

See Sean Michael Kerner's article, The FAQs on FAQs, at http://osdir.com/Article1722.phtml, for descriptions and evaluations of open source FAQ maintenance tools.

In the Subversion project, we choose committers primarily on the Hippocratic Principle: first, do no harm. Our main criterion is not technical skill or even knowledge of the code, but merely that the committer show good judgement. Judgement can mean simply knowing what not to take on. A person might post only small patches, fixing fairly simple problems in the code; but if the patches apply cleanly, do not contain bugs, and are mostly in accord with the project's log message and coding conventions, and there are enough patches to show a clear pattern, then an existing committer will usually propose that person for commit access. If at least three people say yes, and no one objects, then the offer is made. True, we might have no evidence that the person is able to solve complex problems in all areas of the code base, but that does not matter: the person has made it clear that he is capable of at least judging his own abilities. Technical skills can be learned (and taught), but judgement, for the most part, cannot. Therefore, it is the one thing you want to make sure a person has before you give him commit access.

When a new committer proposal does provoke a discussion, it is usually not about technical ability, but rather about the person's behavior on the mailing lists or in IRC. Sometimes someone shows technical skill and an ability to work within the project's formal guidelines, yet is also consistently belligerent or uncooperative in public forums. That's a serious concern; if the person doesn't seem to shape up over time, even in response to hints, then we won't add him as a committer no matter how skilled he is. In a volunteer group, social skills, or the ability to "play well in the sandbox", are as important as raw technical ability. Because everything is under version control, the penalty for adding a committer you shouldn't have is not so much the problems it could cause in the code (review would spot those quickly anyway), but that it might eventually force the project to revoke the person's commit access—an action that is never pleasant and can sometimes be confrontational.

Many projects insist that the potential committer demonstrate a certain level of technical expertise and persistence, by submitting some number of nontrivial patches—that is, not only do these projects want to know that the person will do no harm, they want to know that she is likely to do good across the code base. This is fine, but be careful that it doesn't start to turn committership into a matter of membership in an exclusive club. The question to keep in everyone's mind should be "What will bring the best results for the code?" not "Will we devalue the social status associated with committership by admitting this person?" The point of commit access is not to reinforce people's self-worth, it's to allow good changes to enter the code with a minimum of fuss. If you have 100 committers, 10 of whom make large changes on a regular basis, and the other 90 of whom just fix typos and small bugs a few times a year, that's still better than having only the 10.

The first thing to be said about revoking commit access is: try not to be in that situation in the first place. Depending on whose access is being revoked, and why, the discussions around such an action can be very divisive. Even when not divisive, they will be a time-consuming distraction from productive work.

However, if you must do it, the discussion should be had privately among the same people who would be in a position to vote for granting that person whatever flavor of commit access they currently have. The person herself should not be included. This contradicts the usual injunction against secrecy, but in this case it's necessary. First, no one would be able to speak freely otherwise. Second, if the motion fails, you don't necessarily want the person to know it was ever considered, because that could open up questions ("Who was on my side? Who was against me?") that lead to the worst sort of factionalism. In certain rare circumstances, the group may want someone to know that revocation of commit access is or was being considered, as a warning, but this openness should be a decision the group makes. No one should ever, on her own initiative, reveal information from a discussion and ballot that others assumed were secret.

Once someone's access is revoked, that fact is unavoidably public (see la section intitulée « Avoid Mystery » later in this chapter), so try to be as tactful as you can in how it is presented to the outside world.

Some projects offer gradations of commit access. For example, there might be contributors whose commit access gives them free rein in the documentation, but who do not commit to the code itself. Common areas for partial commit access include documentation, translations, binding code to other programming languages, specification files for packaging (e.g., RedHat RPM spec files, etc.), and other places where a mistake will not result in a problem for the core project.

Since commit access is not only about committing, but about being part of an electorate (see la section intitulée « Who Votes? » in Chapitre 4, Social and Political Infrastructure), the question naturally arises: what can the partial committers vote on? There is no one right answer; it depends on what sorts of partial commit domains your project has. In Subversion we've kept things fairly simple: a partial committer can vote on matters confined exclusively to that committer's domain, and not on anything else. Importantly, we do have a mechanism for casting advisory votes (essentially, the committer writes "+0" or "+1 (non-binding)" instead of just "+1" on the ballot). There's no reason to silence people entirely just because their vote isn't formally binding.

Full committers can vote on anything, just as they can commit anywhere, and only full committers vote on adding new committers of any kind. In practice, though, the ability to add new partial committers is usually delegated: any full committer can "sponsor" a new partial committer, and partial committers in a domain can often essentially choose new committers for that same domain (this is especially helpful in making translation work run smoothly).

Your project may need a slightly different arrangement, depending on the nature of the work, but the same general principles apply to all projects. Each committer should be able to vote on matters that fall within the scope of her commit access, and not on matters outside that, and votes on procedural questions should default to the full committers, unless there's some reason (as decided by the full committers) to widen the electorate.

Regarding enforcement of partial commit access: it's often best not to have the version control system enforce partial commit domains, even if it can. See la section intitulée « Authorization » in Chapitre 3, L'infrastructure technique for the reasons why.

Some projects automatically remove people's commit access if they go a certain amount of time (say, a year) without committing anything. I think this is usually unhelpful and even counterproductive, for two reasons.

First, it may tempt some people into committing acceptable but unnecessary changes, just to prevent their commit access from expiring. Second, it doesn't really serve any purpose. If the main criterion for granting commit access is good judgement, then why assume someone's judgement would deteriorate just because he's away from the project for a while? Even if he completely vanishes for years, not looking at the code or following development discussions, when he reappears he'll know how out of touch he is, and act accordingly. You trusted his judgement before, so why not trust it always? If high school diplomas do not expire, then commit access certainly shouldn't.

Sometimes a committer may ask to be removed, or to be explicitly marked as dormant in the list of committers (see la section intitulée « Avoid Mystery » below for more about that list). In these cases, the project should accede to the person's wishes, of course.

Although the discussions around adding any particular new committer must be confidential, the rules and procedures themselves need not be secret. In fact, it's best to publish them, so people realize that the committers are not some mysterious Star Chamber, closed off to mere mortals, but that anyone can join simply by posting good patches and knowing how to handle herself in the community. In the Subversion project, we put this information right in the developer guidelines document, since the people most likely to be interested in how commit access is granted are those thinking of contributing code to the project.

In addition to publishing the procedures, publish the actual list of committers. The traditional place for this is a file called MAINTAINERS or COMMITTERS in the top level of the project's source code tree. It should list all the full committers first, followed by the various partial commit domains and the members of each domain. Each person should be listed by name and email address, though the address can be encoded to prevent spam (see la section intitulée « Masquer les adresses dans les archives » in Chapitre 3, L'infrastructure technique) if the person prefers that.

Since the distinction between full commit and partial commit access is obvious and well defined, it is proper for the list to make that distinction too. Beyond that, the list should not try to indicate the informal distinctions that inevitably arise in a project, such as who is particularly influential and how. It is a public record, not an acknowledgments file. List committers either in alphabetical order, or in the order in which they arrived.

If someone threatens a fork in your project, keep calm and remember your long-term goals. The mere existence of a fork isn't what hurts a project; rather, it's the loss of developers and users. Your real aim, therefore, is not to squelch the fork, but to minimize these harmful effects. You may be mad, you may feel that the fork was unjust and uncalled for, but expressing that publicly can only alienate undecided developers. Instead, don't force people to make exclusive choices, and be as cooperative as is practicable with the fork. To start with, don't remove someone's commit access in your project just because he decided to work on the fork. Work on the fork doesn't mean that person has suddenly lost his competence to work on the original project; committers before should remain committers afterward. Beyond that, you should express your desire to remain as compatible as possible with the fork, and say that you hope developers will port changes between the two whenever appropriate. If you have administrative access to the project's servers, publicly offer the forkers infrastructure help at startup time. For example, offer them a complete, deep-history copy of the version control repository, if there's no other way for them to get it, so that they don't have to start off without historical data (this may not be necessary depending on the version control system). Ask them if there's anything else they need, and provide it if you can. Bend over backward to show that you are not standing in the way, and that you want the fork to succeed or fail on its own merits and nothing else.

The reason to do all this—and do it publicly—is not to actually help the fork, but to persuade developers that your side is a safe bet, by appearing as non-vindictive as possible. In war it sometimes makes sense (strategic sense, if not human sense) to force people to choose sides, but in free software it almost never does. In fact, after a fork some developers often openly work on both projects, and do their best to keep the two compatible. These developers help keep the lines of communication open after the fork. They allow your project to benefit from interesting new features in the fork (yes, the fork may have things you want), and also increase the chances of a merger down the road.

Sometimes a fork becomes so successful that, even though it was regarded even by its own instigators as a fork at the outset, it becomes the version everybody prefers, and eventually supplants the original by popular demand. A famous instance of this was the GCC/EGCS fork. The GNU Compiler Collection (GCC, formerly the GNU C Compiler) is the most popular open source native-code compiler, and also one of the most portable compilers in the world. Due to disagreements between the GCC's official maintainers and Cygnus Software,^[24] one of GCC's most active developer groups, Cygnus created a fork of GCC called EGCS. The fork was deliberately non-adversarial: the EGCS developers did not, at any point, try to portray their version of GCC as a new official version. Instead, they concentrated on making EGCS as good as possible, incorporating patches at a faster rate than the official GCC maintainers. EGCS gained in popularity, and eventually some major operating system distributors decided to package EGCS as their default compiler instead of GCC. At this point, it became clear to the GCC maintainers that holding on to the "GCC" name while everyone switched to the EGCS fork would burden everyone with a needless name change, yet do nothing to prevent the switchover. So GCC adopted the EGCS codebase, and there is once again a single GCC, but greatly improved because of the fork.

This example shows why you cannot always regard a fork as an unadulteratedly bad thing. A fork may be painful and unwelcome at the time, but you cannot necessarily know whether it will succeed. Therefore, you and the rest of the project should keep an eye on it, and be prepared not only to absorb features and code where possible, but in the most extreme case to even join the fork if it gains the bulk of the project's mindshare. Of course, you will often be able to predict a fork's likelihood of success by seeing who joins it. If the fork is started by the project's biggest complainer and joined by a handful of disgruntled developers who weren't behaving constructively anyway, they've essentially solved a problem for you by forking, and you probably don't need to worry about the fork taking momentum away from the original project. But if you see influential and respected developers supporting the fork, you should ask yourself why. Perhaps the project was being overly restrictive, and the best solution is to adopt into the mainline project some or all of the actions contemplated by the fork—in essence, to avoid the fork by becoming it.

All the advice here assumes that you are forking as a last resort. Exhaust all other possibilities before starting a fork. Forking almost always means losing developers, with only an uncertain promise of gaining new ones later. It also means starting out with competition for users' attention: everyone who's about to download the software has to ask themselves: "Hmm, do I want that one or the other one?" Whichever one you are, the situation is messy, because a question has been introduced that wasn't there before. Some people maintain that forks are healthy for the software ecosystem as a whole, by a standard natural selection argument: the fittest will survive, which means that, in the end, everyone gets better software. This may be true from the ecosystem's point of view, but it's not true from the point of view of any individual project. Most forks do not succeed, and most projects are not happy to be forked.

A corollary is that you should not use the threat of a fork as an extremist debating technique—"Do things my way or I'll fork the project!"—because everyone is aware that a fork that fails to attract developers away from the original project is unlikely to survive long. All observers—not just developers, but users and operating system packagers too—will make their own judgement about which side to choose. You should therefore appear extremely reluctant to fork, so that if you finally do it, you can credibly claim it was the only route left.

Do not neglect to take all factors into account in evaluating the potential success of your fork. For example, if many of the developers on a project have the same employer, then even if they are disgruntled and privately in favor of a fork, they are unlikely to say so out loud if they know that their employer is against it. Many free software programmers like to think that having a free license on the code means no one company can dominate development. It is true that the license is, in an ultimate sense, a guarantor of freedom—if others want badly enough to fork the project, and have the resources to do so, they can. But in practice, some projects' development teams are mostly funded by one entity, and there is no point pretending that that entity's support doesn't matter. If it is opposed to the fork, its developers are unlikely to take part, even if they secretly want to.

If you still conclude that you must fork, line up support privately first, then announce the fork in a non-hostile tone. Even if you are angry at, or disappointed with, the current maintainers, don't say that in the message. Just dispassionately state what led you to the decision to fork, and that you mean no ill will toward the project from which you're forking. Assuming that you do consider it a fork (as opposed to an emergency preservation of the original project), emphasize that you're forking the code and not the name, and choose a name that does not conflict with the project's name. You can use a name that contains or refers to the original name, as long as it does not open the door to identity confusion. Of course it's fine to explain prominently on the fork's home page that it descends from the original program, and even that it hopes to supplant it. Just don't make users' lives harder by forcing them to untangle an identity dispute.

Finally, you can get things started on the right foot by automatically granting all committers of the original project commit access to the fork, including even those who openly disagreed with the need for a fork. Even if they never use the access, your message is clear: there are disagreements here, but no enemies, and you welcome code contributions from any competent source.

If your goal is that your code be accessible by the greatest possible number of developers and derivative works, and you do not mind the code being used in proprietary programs, choose the MIT / X Window System license (so named because it is the license under which the Massachusetts Institute of Technology released the original X Window System code). This license's basic message is "You are free to use this code however you want." It is compatible with the GNU GPL, and it is short, simple, and easy to understand:

Copyright (c) <year> <copyright holders>

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

(Taken from http://www.opensource.org/licenses/mit-license.php.)

If you prefer that your project's code not be used in proprietary programs, or if you at least don't care whether or not it can be used in proprietary programs, choose the GNU General Public License (http://www.fsf.org/licensing/licenses/gpl.html). The GPL is probably the most widely-used free software license in the world today; this instant recognizability is itself one of the GPL's major advantages.

When writing a code library that is meant mainly to be used as part of other programs, consider carefully whether the restrictions imposed by the GPL are in line with your project's goals. In some cases—for example, when you're trying to unseat a competing, proprietary library that does the same thing—it may make more strategic sense to license your code in such a way that it can be mixed into proprietary programs, even though you would otherwise not wish this. The Free Software Foundation even fashioned an alternative to the GPL for such circumstances: the GNU Library GPL, later renamed to the GNU Lesser GPL (most people just use the acronym LGPL, in any case). The LGPL has looser restrictions than the GPL, and can be mixed more easily with non-free code. However, it's also a bit complex and takes some time to understand, so if you're not going to use the GPL, I recommend just using the MIT/X-style license.

A fair amount of open source software is distributed under a BSD license (or sometimes a BSD-style license). The original BSD license was used for the Berkeley Software Distribution, in which the University of California released important portions of a Unix implementation. This license (the exact text may be seen in section 2.2.2 of http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6) was similar in spirit to the MIT/X license, except for one clause:

The presence of that clause not only made the original BSD license GPL-incompatible, it also set a dangerous precedent: as other organizations put similar advertising clauses into their free software—substituting their own organization's name in place of "the University of California, Lawrence Berkeley Laboratory"—software redistributors faced an ever-increasing burden in what they were required to display. Fortunately, many of the projects that used this license became aware of the problem, and simply dropped the advertising clause. In 1999, even the University of California did so.

The result is the revised BSD license, which is simply the original BSD license with the advertising clause removed. However, this history makes the phrase "BSD license" a bit ambiguous: does it refer to the original, or the revised version? This is why I prefer the MIT/X license, which is essentially equivalent, and which does not suffer from any ambiguity. However, there is perhaps one reason to prefer the revised BSD license to the MIT/X license, which is that the BSD includes this clause:

It's not clear that without such a clause, a recipient of the software would have had the right to use the licensor's name anyway, but the clause removes any possible doubt. For organizations worried about trademark control, therefore, the revised BSD license may be slightly preferable to MIT/X. In general, however, a liberal copyright license does not imply that recipients have any right to use or dilute your trademarks — copyright law and trademark law are two different beasts.

If you wish to use the revised BSD license, a template is available at http://www.opensource.org/licenses/bsd-license.php.

Most projects never collect CLAs or copyright assignments from their contributors. Instead, they accept code whenever it seems reasonably clear that the contributor intended it to be incorporated into the project.

Under normal circumstances, this is okay. But every now and then, someone may decide to sue for copyright infringement, alleging that they are the true owner of the code in question and that they never agreed to its being distributed by the project under an open source license. For example, the SCO Group did something like this to the Linux project, see http://en.wikipedia.org/wiki/SCO-Linux_controversies for details. When this happens, the project will have no documentation showing that the contributor formally granted the right to use the code, which could make some legal defenses more difficult.

CLAs probably offer the best tradeoff between safety and convenience. A CLA is typically an electronic form that a developer fills out and sends in to the project. In many jurisdictions, email submission is enough. A secure digital signature may or may not be required; consult a lawyer to find out what method would be best for your project.

Most projects use two slightly different CLAs, one for individuals, and one for corporate contributors. But in both types, the core language is the same: the contributor grants the project "...perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute [the] Contributions and such derivative works." Again, you should have a lawyer approve any CLA, but if you get all those adjectives into it, you're probably fine.

When you request CLAs from contributors, make sure to emphasize that you are not asking for actual copyright assignment. In fact, many CLAs start out by reminding the reader of this:

Here are some examples:

Copyright transfer means that the contributor assigns to the project copyright ownership on her contributions. Ideally, this is done on paper and either faxed or snail-mailed to the project.

Some projects insist on full assignment because having a single legal entity own the copyright on the entire code base can be useful if the terms of the open source license ever need to be enforced in court. If no single entity has the right to do it, all the contributors might have to cooperate, but some might not have time or even be reachable when the issue arises.

Different organizations apply different amounts of rigor to the task of collecting assignments. Some simply get an informal statement from a contributor on a public list mailing list—something to the effect of "I hereby assign copyright in this code to the project, to be licensed under the same terms as the rest of the code." At least one lawyer I've talked to says that's really enough, presumably because it happens in a context where copyright assignment is normal and expected anyway, and because it represents a bona fide effort on the project's part to ascertain the developer's true intentions. On the other hand, the Free Software Foundation goes to the opposite extreme: they require contributors to physically sign and mail in a piece of paper containing a formal statement of copyright assignment, sometimes for just one contribution, sometimes for current and future contributions. If the developer is employed, the FSF asks that the employer sign it too.

The FSF's paranoia is understandable. If someone violates the terms of the GPL by incorporating some of their software into a proprietary program, the FSF will need to fight that in court, and they want their copyrights to be as airtight as possible when that happens. Since the FSF is copyright holder for a lot of popular software, they view this as a real possibility. Whether your organization needs to be similarly scrupulous is something only you can decide, in consultation with lawyers. In general, unless there's some specific reason why your project needs full copyright assignment, just go with CLAs; they're easier for everyone.