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.oldPuis, 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.diffCeci 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