  HOWTO sur la publication de logiciels
  Eric S. Raymond <esr@thyrsus.com> Traduction par Thierry
  Bzecourt <thbzcrt@worldnet.fr>
  1.0, 21 Novembre 1998

  Ce HOWTO dcrit des mthodes de publication de logiciel convenant 
  des projets de logiciel libre pour Linux. En adoptant ces rgles, vous
  permettrez  vos utilisateurs de compiler votre code et de l'utiliser
  plus facilement, et  d'autres dveloppeurs de mieux le comprendre et
  de vous aider  l'amliorer.  Ce document est  lire absolument par
  les dveloppeurs dbutants. Ceux qui ont plus d'exprience devraient
  le parcourir  nouveau au moment de publier un nouveau projet. Il sera
  mis  jour priodiquement afin de reflter l'volution des rgles de
  bonne pratique.
  ______________________________________________________________________

  Table des matires


  1. Introduction

     1.1 Raison d'tre de ce document
     1.2 Nouvelles versions de ce document

  2. Rgles d'usage pour le nommage de votre projet et de votre archive

     2.1 Utilisez le style de nommage GNU, avec un prfixe suivi d'un numrotage du type majeur.mineur.patch.
     2.2 Choisissez avec le plus grand soin un prfixe unique et facile  taper

  3. Rgles d'usage du dveloppement

     3.1 Ecrivez soit en C ANSI pur, soit dans un langage de script portable
     3.2 Respectez les rgles de portabilit du C
     3.3 Utilisez autoconf/automaker/autoheader
     3.4 Soignez la rigueur de votre code avant chaque nouvelle version

  4. Rgles d'usage pour la mise au point de la distribution

     4.1 Assurez-vous que vos archives se dcompactent toujours dans un rpertoire nouveau et unique.
     4.2 Ecrivez un README
     4.3 Adoptez les conventions courantes de nommage des fichiers

  5. Comment communiquer

     5.1 Faites une annonce dans c.o.l.a
     5.2 Faites une annonce dans un forum de discussion adquat
     5.3 Ayez un site Web
     5.4 Hbergez des listes de diffusion pour votre projet
     5.5 Publiez dans les archives les plus importantes
     5.6 Fournissez des RPM


  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn


  11..11..  RRaaiissoonn dd''ttrree ddee ccee ddooccuummeenntt

  Un vaste ensemble de traditions relatives au dveloppement de
  logiciels libres permet  d'autres personnes de porter le code plus
  facilement, de l'utiliser et de participer  son dveloppement.
  Certaines de ces conventions sont des traditions du monde Unix
  antrieures  Linux ; d'autres ont t suscites rcemment par
  l'apparition de nouveaux outils et de nouvelles technologies comme le
  World Wide Web.
  Ce document vous aidera  acqurir ces rgles d'usage. Il se compose
  de plusieurs sections thmatiques, chacune contenant une liste de
  points  vrifier. Considrez que ces sections sont pour votre
  distribution comme la liste de contrle qu'un pilote d'avion vrifie
  avant le dcollage.


  11..22..  NNoouuvveelllleess vveerrssiioonnss ddee ccee ddooccuummeenntt

  Ce document sera envoy chaque mois dans le forum de discussion
  comp.os.linux.answers . Ce document est archiv sur plusieurs sites
  FTP Linux, dont sunsite.unc.edu dans le rpertoire
  pub/Linux/docs/HOWTO.

  Vous pouvez aussi voir la dernire version, en anglais, de ce HOWTO
  sur le World Wide Web  l'URL
  <http://sunsite.unc.edu/LDP/HOWTO/Software-Release-Practice.html>. La
  version franaise est disponible  l'adresse
  <http://sunsite.unc.edu/pub/Linux/docs/HOWTO/translations/fr>.

  Vous pouvez envoyer vos questions et vos commentaires sur ce HOWTO 
  Eric S. Raymond, esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>.


  22..  RRgglleess dd''uussaaggee ppoouurr llee nnoommmmaaggee ddee vvoottrree pprroojjeett eett ddee vvoottrree aarrcchhiivvee

  Au fur et  mesure que s'accrot la charge de travail des
  gestionnaires d'archives comme Sunsite, le site PSA ou le CPAN, les
  soumissions sont de plus en plus souvent traites, en tout ou en
  partie, par des programmes (et non en totalit par des humains).

  Il est donc trs important que le nom de votre projet et celui de
  votre fichier d'archive suivent des rgles prcises, afin que des
  programmes informatiques puissent les analyser et les comprendre.


  22..11..  nnuummrroottaaggee dduu ttyyppee mmaajjeeuurr..mmiinneeuurr..ppaattcchh..  UUttiilliisseezz llee ssttyyllee ddee
  nnoommmmaaggee GGNNUU,, aavveecc uunn pprrffiixxee ssuuiivvii dd''uunn

  Vous faciliterez la vie  tout le monde en donnant  vos archives des
  noms dans le style GNU : un prfixe-racine alphanumrique tout en
  minuscules, suivi par un tiret, puis un numro de version, une
  extension et d'autres suffixes.

  Supposons que vous ayez un projet nomm "toto", qui en est  la
  version 1, mise  jour 2, niveau 3. S'il est compos d'une seule
  archive (sans doute le code source), voici  quoi devrait ressembler
  son nom :


     ttoottoo--11..22..33..ttaarr..ggzz
        L'archive des sources


     ttoottoo..llssmm
        Le fichier LSM (si vous l'envoyez  Sunsite).


  N'utilisez _p_a_s les noms suivants :


     ttoottoo112233..ttaarr..ggzz
        Beaucoup de programmes croiront qu'il s'agit du fichier
        d'archive d'un projet nomm `toto123', sans numro de version.


     ttoottoo11..22..33..ttaarr..ggzz
        Beaucoup de programmes croiront qu'il s'agit de l'archive d'un
        projet nomm `toto1'  la version 2.3.


     ttoottoo--vv11..22..33..ttaarr..ggzz
        Beaucoup de programmes prendront cela pour un projet nomm
        `toto-v1'.


     ttoo__ttoo--11..22..33..ttaarr..ggzz
        Le caractre soulign est difficile  prononcer,  taper, et 
        retenir.


     TTooTToo--11..22..33..ttaarr..ggzz
        A moins que vous vouliez _v_r_a_i_m_e_n_t ressembler  un accroc du
        marketing. L encore, c'est difficile  prononcer,  taper et 
        retenir.

  Si vous voulez faire sparment une archive de sources et une archive
  de binaires, ou diffrentes archives de binaires, ou encore indiquer
  un certain type d'option de compilation dans le nom de l'archive,
  rajoutez pour cela une extension _a_p_r__s le numro de version. Voici
  quelques exemples :


     ttoottoo--11..22..33..ssrrcc..ttaarr..ggzz
        sources


     ttoottoo--11..22..33..bbiinn..ttaarr..ggzz
        binaires, type non spcifi


     ttoottoo--11..22..33..bbiinn..EELLFF..ttaarr..ggzz
        binaires ELF


     ttoottoo--11..22..33..bbiinn..EELLFF..ssttaattiicc..ttaarr..ggzz
        binaires ELF lis statiquement


     ttoottoo--11..22..33..bbiinn..SSPPAARRCC..ttaarr..ggzz
        binaires pour SPARC

  N'utilisez _p_a_s des noms comme `toto-ELF.1.2.3.tar.gz', car les
  programmes ont beaucoup de mal  sparer un infixe (tel que `ELF') de
  la racine du mot.

  Un bon schma de nommage gnrique contient, dans l'ordre, les parties
  suivantes :


  1. prfixe du projet

  2. tiret

  3. numro de version

  4. point

  5. "src" ou "bin" (optionnel)

  6. point ou tiret (un point de prfrence)

  7. type de binaire et options (optionnel)

  8. extensions relatives au mode d'archivage et de compression


  22..22..  ttaappeerr CChhooiissiisssseezz aavveecc llee pplluuss ggrraanndd ssooiinn uunn pprrffiixxee uunniiqquuee eett
  ffaacciillee 

  Le prfixe-racine devrait tre le mme pour tous les fichiers d'un
  projet, et il devrait tre facile  lire,  taper et  retenir.
  N'utilisez pas le caractre "soulign". Et ne mettez pas de majuscules
  ou de MajusculesIntrieures sans une trs bonne raison -- cela drange
  le trajet naturel de l'oeil humain, et vous aurez l'air de faire du
  marketing.

  C'est difficile de s'y retrouver lorsque deux projets ont le mme nom.
  Assurez-vous donc, dans la mesure du possible, qu'il n'y a pas de
  conflit de nommage avant de publier votre premire version. Un bon
  endroit pour le vrifier est l'index de Sunsite
  <http://sunsite.unc.edu/pub/Linux>.


  33..  RRgglleess dd''uussaaggee dduu ddvveellooppppeemmeenntt

  La plupart de ces rgles visent  assurer la portabilit, non
  seulement entre les diffrentes distributions de Linux, mais aussi
  avec d'autres varits d'Unix. La portabilit vers Unix n'est pas
  seulement une question de professionnalisme ou de savoir-vivre entre
  programmeurs, c'est aussi une assurance non ngligeable contre les
  volutions futures de Linux lui-mme.

  D'autres personnes finiront par essayer de compiler votre code dans
  d'autres environnements que Linux ; avec la portabilit, vous recevrez
  moins de messages ennuyeux de la part d'utilisateurs perplexes.


  33..11..  EEccrriivveezz ssooiitt eenn CC AANNSSII ppuurr,, ssooiitt ddaannss uunn llaannggaaggee ddee ssccrriipptt
  ppoorrttaabbllee

  Pour des raisons de portabilit et de stabilit, il est fortement
  recommand d'crire soit en C ANSI pur, soit dans un langage de script
  dont la portabilit soit garantie par une implmentation multi-
  plateforme unique.

  Parmi les langages de script, Python, Perl, Tcl et Emacs Lisp
  respectent ce critre. Le bon vieux shell _n_e _c_o_n_v_i_e_n_t _p_a_s ; il existe
  trop d'implmentations diffrentes, chacune ayant des particularits
  subtiles, et l'environnement du shell est souvent transform de
  manire imprvisible par des configurations propres  chaque
  utilisateur, comme les alias.

  Java promet beaucoup sur le plan de la portabilit, mais les
  implmentations disponibles sur Linux sont encore sommaires et mal
  intgres dans le systme d'exploitation. Java est encore un choix
  exotique, bien qu'il ait de fortes chances de gagner en popularit
  lorsqu'il aura plus de maturit.


  33..22..  RReessppeecctteezz lleess rrgglleess ddee ppoorrttaabbiilliitt dduu CC

  Si vous crivez en C, n'hsitez pas  utiliser  fond les
  fonctionnalits dcrites dans la norme ANSI -- y compris les
  prototypes de fonction, qui vous aideront  reprer les incohrences
  entre modules. Les compilateurs du type K&R relvent du pass.


  En revanche, ne supposez _p_a_s que certaines caractristiques
  spcifiques  GCC comme l'option `-pipe' ou les fonctions imbriques
  sont disponibles. Cela vous poursuivra et vous vous en repentirez le
  jour o quelqu'un portera votre logiciel vers un systme autre que
  Linux, et dpourvu de GCC.


  33..33..  UUttiilliisseezz aauuttooccoonnff//aauuttoommaakkeerr//aauuttoohheeaaddeerr

  Si vous crivez en C, utilisez autoconf/automaker/autoheader pour
  assurer la portabilit, vrifier la configuration du systme et
  affiner vos makefiles. De nos jours, les gens qui compilent  partir
  des sources s'attendent  devoir juste taper "configure; make" et que
  tout se compile proprement - sans la moindre erreur.


  33..44..  SSooiiggnneezz llaa rriigguueeuurr ddee vvoottrree ccooddee aavvaanntt cchhaaqquuee nnoouuvveellllee vveerrssiioonn

  Si vous crivez en C, faites une compilation de test avec l'option
  -Wall et corrigez les erreurs rsultantes, au moins une fois avant
  chaque nouvelle version. On trouve comme cela un nombre surprenant
  d'erreurs. Pour tre vraiment complet, compilez aussi avec l'option
  -pedantic.

  Si vous crivez en Perl, vrifiez votre code avec perl -c, perl -w et
  perl -T avant chaque nouvelle version (consultez la documentation de
  Perl pour plus d'information).


  44..  RRgglleess dd''uussaaggee ppoouurr llaa mmiissee aauu ppooiinntt ddee llaa ddiissttrriibbuuttiioonn

  Les indications qui suivent montrent  quoi votre distribution devrait
  ressembler lorsqu'on la rcupre et qu'on la dcompacte.


  44..11..  rrppeerrttooiirree nnoouuvveeaauu eett uunniiqquuee..  AAssssuurreezz--vvoouuss qquuee vvooss aarrcchhiivveess ssee
  ddccoommppaacctteenntt ttoouujjoouurrss ddaannss uunn

  L'erreur la plus agaante que font les dveloppeurs novices est de
  fabriquer des archives qui dcompactent les fichiers et rpertoires de
  la distribution dans le rpertoire courant, avec le risque d'craser
  des fichiers dj prsents. _N_e _f_a_i_t_e_s _j_a_m_a_i_s _c_e_l_a _!

  A la place, faites en sorte que les fichiers de vos archives partagent
  le mme rpertoire, avec un nom drivant de celui du projet. Ainsi,
  ils se placeront dans un seul rpertoire, juste _e_n_-_d_e_s_s_o_u_s du
  rpertoire courant.

  Voici un moyen de raliser cela dans un makefile, en supposant que le
  rpertoire de votre distribution est `toto' et que SRC est une
  variable contenant la liste des fichiers de votre distribution. Vous
  devez avoir GNU tar 1.13.


  VERS=1.0
  toto-$(VERS).tar.gz:
          tar --name-prefix='toto-$(VERS)/' -czf toto-$(VERS).tar.gz $(SRC)



  Si votre version de tar est plus ancienne, faites quelque chose dans
  ce genre :




  toto-$(VERS).tar.gz:
          @ls $(SRC) | sed s:^:toto-$(VERS)/: >MANIFEST
          @(cd ..; ln -s toto toto-$(VERS))
          (cd ..; tar -czvf toto/toto-$(VERS).tar.gz `cat toto/MANIFEST`)
          @(cd ..; rm toto-$(VERS))




  44..22..  EEccrriivveezz uunn RREEAADDMMEE

  Fournissez un fichier nomm README ou READ.ME, qui donne une vision
  d'ensemble de votre distribution. C'est une vieille convention, et
  c'est le premier fichier que l'intrpide explorateur lira aprs avoir
  extrait les sources (Note du traducteur : le fichier README, comme son
  nom l'indique, est crit en anglais afin d'tre lisible par le plus
  grand nombre de personnes possible. Vous pouvez aussi, si vous le
  jugez utile, fournir une traduction franaise dans un fichier nomm
  LISEZMOI, pour les utilisateurs francophones).

  Voici quelques lments qu'il est bon d'avoir dans un README :


    Une description brve du projet.

    Un lien vers le site Web du projet, le cas chant.

    Des indications sur l'environnement de compilation du dveloppeur
     et sur les possibles problmes de portabilit.

    Un plan d'ensemble des fichiers et sous-rpertoires importants.

    Les instructions de compilation et d'installation, ou bien un lien
     vers le fichier les contenant (habituellement INSTALL).

    Le nom des responsables et des contributeurs, ou un lien vers le
     fichier contenant ces noms (habituellement CREDITS).

    Les dernires nouvelles relatives au projet, ou un lien vers un
     fichier les contenant (habituellement NEWS).


  44..33..  AAddoopptteezz lleess ccoonnvveennttiioonnss ccoouurraanntteess ddee nnoommmmaaggee ddeess ffiicchhiieerrss

  Avant mme d'avoir regard le README, votre intrpide explorateur aura
  parcouru la liste des fichiers dans rpertoire principal de votre
  distribution. Ces noms, par eux-mmes, contiennent de l'information.
  En suivant certaines rgles de nommage, vous donnerez  l'explorateur
  de bons indices pour orienter son parcours.

  Voici quelques noms recommands pour les fichiers du rpertoire
  principal, avec leur signification. Tous ne sont pas indispensables
  dans chaque projet.


     RREEAADDMMEE oouu RREEAADD..MMEE
        le plan d'ensemble,  lire en premier


     IINNSSTTAALLLL
        instructions de configuration, de compilation et d'installation


     CCRREEDDIITTSS
        liste des contributeurs du projet

     NNEEWWSS
        dernires nouvelles


     HHIISSTTOORRYY
        histoire du projet


     CCOOPPYYIINNGG
        termes de la licence (convention GNU)


     LLIICCEENNSSEE
        termes de la licence


     MMAANNIIFFEESSTT
        liste des fichiers


     FFAAQQ
        Foire Aux Questions pour le projet, au format texte.


     TTAAGGSS
        Fichier de tags gnr automatiquement, pour tre utilis par
        Emacs ou vi

  Remarquez que la convention gnrale est que les fichiers dont le nom
  ne comporte que des majuscules sont des fichiers d'information sur le
  projet lui-mme, et ne sont pas des lments du systme  compiler.


  55..  CCoommmmeenntt ccoommmmuunniiqquueerr

  Votre logiciel n'apportera pas grand'chose  l'univers si vous tes le
  seul  connatre son existence. De plus, en tablissant une prsence
  visible sur Internet pour votre projet, vous pourrez recruter plus
  facilement des utilisateurs et des co-dveloppeurs. On le fait
  habituellement comme ceci :


  55..11..  FFaaiitteess uunnee aannnnoonnccee ddaannss cc..oo..ll..aa

  Annoncez vos nouvelles versions dans comp.os.linux.announce
  <news:comp.os.linux.announce>. Non seulement ce forum est lu par un
  grand nombre de personnes, mais c'est aussi un fournisseur important
  pour des sites Web d'information comme Freshmeat
  <http://www.freshmeat.net>.


  55..22..  FFaaiitteess uunnee aannnnoonnccee ddaannss uunn ffoorruumm ddee ddiissccuussssiioonn aaddqquuaatt

  Trouvez un forum USENET dont le thme de discussion est directement
  concern par votre application, et faites-y aussi votre annonce.
  N'envoyez votre message qu'aux endroits o la _f_o_n_c_t_i_o_n remplie par
  votre logiciel est pertinente, et restez mesur.

  Si (par exemple) vous publiez un programme en Perl qui interroge des
  serveurs IMAP, vous devriez probablement envoyez un message dans
  comp.mail.imap. Mais srement pas dans comp.lang.perl,  moins que le
  programme utilise de manire instructive des techniques Perl avances.

  Votre annonce devrait aussi contenir l'URL du site Web de votre
  projet.

  55..33..  AAyyeezz uunn ssiittee WWeebb

  Si vous comptez tablir une communit substantielle d'utilisateurs ou
  de dveloppeurs autour de votre projet, celui-ci devrait avoir son
  site Web. Voici des lments que l'on trouve habituellement sur un
  site Web :

    La charte du projet (pourquoi il existe, quelle est son audience,
     etc).

    Des liens pour le tlchargement des sources.

    Des instructions relatives  l'inscription  la ou les liste(s) de
     diffusion.

    Une FAQ (Foire Aux Questions).

    Une version en HTML de la documentation.

    Des liens vers des projets proches et/ou concurrents.

  Certains projets ont mme une URL pour un accs anonyme 
  l'arborescence principale du code source.


  55..44..  HHbbeerrggeezz ddeess lliisstteess ddee ddiiffffuussiioonn ppoouurr vvoottrree pprroojjeett

  Il est d'usage d'avoir une liste de dveloppement prive qui permet
  aux collaborateurs du projet de communiquer et d'changer des patchs.
  Vous voudrez peut-tre crer en plus une liste d'annonces pour les
  gens qui veulent tre informs de la progression du projet.


  55..55..  PPuubblliieezz ddaannss lleess aarrcchhiivveess lleess pplluuss iimmppoorrttaanntteess

  Depuis plusieurs annes, le site Sunsite
  <http://www.sunsite/unc.edu/pub/Linux/> est le plus important des
  endroits d'change de logiciels pour Linux.

  Voici quelques autres sites notables :


    le site Python Software       Activity <http://www.python.org>
     (pour les logiciels crits en Python).

    le CPAN <http://language.perl.com/CPAN> ou Rseau d'Archives Perl
     Global (pour les logiciels crits en Perl).


  55..66..  FFoouurrnniisssseezz ddeess RRPPMM

  Le standard de facto pour les archives de binaires est celui
  qu'utilise gestionnaire d'archives de Red Hat, ou RPM. Il est prsent
  dans la distribution de Linux la plus populaire, et il est support
  dans les faits par toutes les autres distributions (sauf Debian et
  Slackware).

  C'est donc une bonne ide de fournir, sur le site de votre projet,
  aussi bien des RPM installables que des archives de sources.







