Mettez-vous dans la peau d'une personne qui cherche une solution pour résoudre son problème. Cette personne va tomber d'une manière ou d'une autre sur votre projet car on suppose qu'il répond à son besoin. Cette personne doit facilement identifier que votre projet est une bonne solution. Pour cela, un site web bien organisé doit l'amener à se faire une bonne idée de votre projet. Un petit descriptif de votre projet en 10 lignes, quelques captures d'écran si cela se justifie, et le lien "download" visible au moins sur la page d'accueil, et la personne devient un utilisateur potentiel.

Cette personne a été séduite parce que votre projet est bien documenté sur le site web: il contient aussi une page pour télécharger le manuel utilisateur, il contient des liens vers la Foire Aux Questions et vers la liste de diffusion. Bref, la personne a vu qu'en cas de problème avec votre projet, elle pourrait toujours trouver de l'aide par différents moyens. En d'autres termes, votre projet est loin d'être une boîte noire, et ce n'est pas le moindre problème qui va pousser la personne à aller voir ailleurs.

Maintenant que cette personne a téléchargé votre projet, elle va utilise les commandes classiques:

tar xvzf le_projet.tar.gz
cd le_projet
more README
			

Donc votre projet doit contenir un fichier README, ou à défaut, un fichier INSTALL, les deux étant le mieux. Le plus agréable est d'avoir un fichier README qui commence par le nom du projet, sans numéro de version. Si on met un numéro de version, il faut le maintenir à jour, et au moindre oubli, cela sèmera la confusion chez l'utilisateur qui aura téléchargé la version 1.4.2 et s'étonnera d'avoir un fichier README contenant le numéro 1.4.1. Le numéro de version doit se trouver dans le nom du paquet téléchargé, et il vaut mieux éviter de le mettre ailleurs, pour éviter la redondance. Je parlerai beaucoup de la redondance plus bas comme un défaut, et comment s'en passer. Ici, on s'en passe en ayant un fichier README intemporel. Idem pour le fichier INSTALL. Le fichier README doit continuer par les opérations à suivre pour installer le logiciel. C'est là qu'un texte "see the INSTALL file" (voir le fichier INSTALL) a sa place, car dès la troisième ligne, on peut avoir un descriptif du projet. Ce fichier README peut aussi contenir la liste des fichiers et répertoires notables, comme le fichier INSTALL sus-cité, les fichiers BUGS, NEWS, ChangeLog, TODO et autres, les répertoires src, doc, contrib, etc.

Lui a déjà installé plusieurs version successives de votre projet car il a vu que certaines d'entre elles corrigeaient des bogues génant pour lui. Les fichiers README et INSTALL, cela fait longtemps qu'il ne les lit plus, lui. Par contre, les fichiers ChangeLog et/ou NEWS l'interesseront pour savoir s'il doit installer une nouvelle version (prenant le risque de voir apparaître un nouveau bogue, prix à payer pour la nouvelle fonctionnalité) ou s'il vaut mieux au contraire rester à l'ancienne version étant donné que les nouvelles fonctionnalités de la version la plus récente ne l'interessent pas. Ayez donc un fichier ChangeLog et/ou NEWS à la disposition de l'utilisateur. Chacun est libre de l'utilisation de ces fichiers, mais une manière de faire qui me semble fonctionner bien est d'avoir un fichier ChangeLog qui contient toutes les modifications apportées au projet. Cela permet ainsi de suivre l'évolution du projet, de pouvoir trouver l'apparition d'un bogue ou d'une fonctionnalité, ou même de pouvoir citer le numéro de version du programme qui corrigeait un bogue dont on vient de vous soumettre un rapport. Le fichier ChangeLog est la mémoire du projet dans ce cas. Comme une telle utilisation le rend peu agréable à lire, un autre fichier, NEWS, indique les changements majeurs: c'est le résumé de ChangeLog et son contenu doit être lisible.

D'autres fichiers peuvent aussi intéresser l'utilisateur expérimenté, voire l'utilisateur novice. L'un est une liste des bogues connus qui ne peuvent être résolus, ou alors dont la résolution sort du cadre du projet. Ainsi, si une distribution diffuse une librairie ou tout autre fichier dont votre projet se sert, et que le fichier est corrompu ou bogué, vous pouvez vous attendre à recevoir de nombreux courriers électroniques concernant ce bogue. Plutôt que de répondre à chaque fois, un descriptif dans un fichier, BUGS par exemple, permet à l'utilisateur d'identifier et de résoudre plus facilement des problèmes qui ne dépendent pas de vous.

Inversement au fichier BUGS, un fichier TODO permet de recencer les fonctionnalités manquantes ainsi que les bogues à corriger. Et lorsque le bogue a été corrigé ou que la fonctionnalité a été ajoutée, la ligne correspondante dans le fichier TODO peut être déplacée dans le fichier ChangeLog.

Enfin, n'oubliez pas de mettre la manière de vous joindre dans un fichier facilement identifiable, par exemple AUTHORS.

Historique d'une modification. Habituellement, une nouvelle fonctionnalité est réclamée par un utilisateur (qui peut être vous d'ailleurs). Si vous ne codez pas cette fonctionnalité à la réception de la demande, il faut la mettre immédiatement dans le fichier TODO, et mettre l'adresse de la personne qui a réclamé la fonctionnalité à la suite. Moi, je fais un copier/coller du courrier électronique. S'il arrive en français et que je n'ai pas le temps de le traduire, je préfère le mettre tel quel dans le fichier TODO plutôt que de risquer de perdre le courrier (le supprimer ou le perdre parmi la tonne de courrier). Il est important de ne pas oublier de mettre l'adresse électronique de la personne car si après un certain temps on n'arrive plus à cerner la demande, il faut pouvoir recontacter la personne. D'autre part, si on mène le projet en équipe, une autre personne peut prendre contact pour plus de précisions sans avoir à demander qui a écrit la demande dans le fichier TODO puis qui a fait la demande initialement.

Le format du fichier TODO n'est pas vraiment défini: chacun fait ce qu'il veut. Cependant, trois parties peuvent organiser le fichier:

Lorsque la modification est effectuée, vous pouvez envoyer un courrier à la personne qui l'a demandée pour lui signaler d'une part le changement, et d'autre part un peu de béta-test de sa part sur la fonctionnalité: qui de mieux placé que cette personne pour tester la nouveauté? A nouveau, avoir stocké l'adresse est utile pour cela. De plus, garder cette adresse dans le fichier ChangeLog permet un traitement à but statistique. Ou même tout simplement, dans les remerciements, il devient facile d'obtenir la liste des contributeurs.

Cette liste des contributeurs, mettez-la dans le fichier AUTHORS. C'est une des plus belles récompenses pour un contributeur que d'avoir son nom dans ce fichier. Il est déjà plaisant d'avoir un morceau de son code dans un projet, mais avoir son nom dans le fichier AUTHORS ajoute une reconnaissance du travail du contributeur. Dans ce fichier AUTHORS, mettez donc au début votre nom, adresse électronique et une mention comme quoi vous coordinez le projet. Puis, mettez les noms des contributeurs réguliers, avec un résumé de leurs contributions, comme "auteur de telle partie du code", ou "coordinateur du module trucmuche". Et ensuite, la liste des contributeurs occasionnels accompagnée de l'adresse électronique, sans forcément une mention de leur participation car la correction d'un bogue, par exemple, présente peu d'intérêt d'être signalée à cet endroit.

Pour l'anecdote, j'avais eu quelques échanges de courriers électroniques avec une personne qui avait travaillé sur une modification d'un de mes projets. Et je voulais lui poser une question quelques mois après sur la manière d'étendre cette modification. C'est parce que j'avais noté son adresse dans le fichier ChangeLog du projet que j'ai pu facilement recontacter cette personne (mon lecteur de courrier électronique fait le ménage dans les courriers envoyés tous les mois).