Projet de documentation FreeBSD : Proposer de la documentation

Je viens d’écrire de la documentation. Comment puis-je la soumettre ?

Avant tout, merci d’avoir pris le temps de le faire.

Vous devez rendre votre documentation accessible aux relecteurs. Si vous le pouvez, mettez votre travail sur un site FTP ou web.

Enfin, postez un message dans la liste de diffusion FreeBSD-doc, accompagné d’un bref descriptif de la documentation et d’un lien vers elle, tout en sollicitant des réactions.

Si, pour une raison ou pour une autre, vous ne pouvez pas mettre votre documentation sur un site FTP ou sur un site web, vous pouvez l’envoyer directement sur la liste de diffusion FreeBSD-doc. Si vous le faites, merci d’envoyer uniquement des documents au format texte simple.

Vous devriez probablement envoyer une copie du message aux autres listes de diffusion concernées. Par exemple, une documentation traitant de l’utilisation de CVSup pour garder votre hiérarchie de code source à jour intéressera les abonnés aux listes de diffusion FreeBSD-current et FreeBSD-stable

Une fois votre documentation examinée par les abonnés, et que vous aurez le cas échéant incorporé les suggestions que vous jugerez bonnes, vous pouvez la soumettre à examen.

Pour ceci, faites-en un fichier tar. Si votre documentation est composée de trois fichiers un, deux, et trois, et que vous voulez tout regrouper dans doc.tar, tapez :

% tar cf doc.tar un deux trois

dont c’est précisément le rôle. Puis compressez le fichier tar,

% gzip -9 doc.tar

qui produira doc.tar.gz.

Enfin, encodez le fichier de façon à ce qu’il ne soit pas modifié par les logiciels de courrier électronique.

% uuencode doc.tar.gz doc.tar.gz > doc.uue

Vous devez ensuite en informer le Projet de Documentation. La manière correcte de le faire est d’utiliser la commande send-pr, qui devrait être installée sur votre machine. Le formulaire de rapport de bogue peut aussi être employé.

Procédez ainsi afin que votre requête puisse être enregistrée. Lorsque vous soumettez un PR (Problem Report), un numéro unique lui est attribué. L’un des responsables peut ainsi s’attribuer la requête PR, et assurer la liaison avec vous dans l’optique d’intégrer la nouvelle documentation. Pour plus d’informations, consultez Ecrire des rapports de bogue pour FreeBSD.

send-pr en lui-même est plutôt simple. Tout ce qu’il fait est d’envoyer un message électronique dans un formatage adapté à une adresse particulière. Lorsque vous lancez send-pr, vous serez amené à rédiger un message à partir de votre éditeur (vraisemblalement vi ou emacs) avec quelques instructions sur cette étape.

Assurez-vous que "Category" est bien sur "docs" et que "Class" est sur l’un des "change-request". Et n’oubliez pas d’inclure le fichier .uue que vous avez créé précédemment dans le corps du PR.

Lorsque vous sortirez de l’éditeur, le PR sera expédié électroniquement au bon endroit. Vous recevrez peu après un accusé de réception accompagné du numéro attribué à votre PR, permettant de suivre l’évolution du travail.

J’ai procédé à quelques changements sur une documentation existante, comment puis-je les soumettre ?

Encore une fois, nous vous remercions d’avoir pris le temps de faire ceci.

Premièrement, vous devez produire un fichier spécifique appelé diff. Ce fichier diff montre simplement les changements que vous avez faits. Ceci rend le travail du responsable plus aisé, afin de voir précisément ce que vous avez changé, et permet de vous éviter de perdre beaucoup de temps à l’expliquer (bien que vous devriez tout de même expliquer pourquoi vous avez jugé que les changements devaient être faits).

Pour faire un "diff", vous devez :

Faire une copie du fichier que vous allez modifier. Si vous modifiez foo.xml, tapez
```
% cp foo.xml foo.xml.old
```

Puis, procédez à vos modifications sur foo.xml.

% vi foo.xml
... tap tap tap ...

... testez les changements, relisez pour corriger les coquilles, etc...

Faites le diff. La commande est la suivante :
```
% diff -u foo.xml.old foo.xml > foo.diff
```
Ceci repère les différences entre les deux fichiers, et les écrit dans le fichier foo.diff.

Vous pouvez maintenant envoyer foo.diff au projet. Envoyez un PR comme décrit plus haut et n’oubliez pas d’inclure le fichier foo.diff dans le corps du PR.

Projet de Documentation FreeBSD : Accueil