From Fedora Project Wiki

Directives pour l'utilisation du FDP CVS

Introduction

Le CVS, ou Concurrent Versions System (Système de gestion de versions), est un ensemble de logiciels qui permet de travailler coopérativement sur un ensemble de fichiers tel que dans le cadre d'un projet de développement ou de documentation. Pour en savoir plus à propos du CVS, vous pouvez lire une des pages suivantes :

L'utilisation du CVS par le FDP (Fedora Documentation Project ou Projet de documentation Fedora) est soumise à toutes les normes, les règles et les directives établies par le Projet Fedora. L'accès au CVS est accordé aux utilisateurs par le biais du Fedora account system .

Le CVS anonyme

Vous pouvez accéder aux fichiers du Projet de documentation Fedora en vous servant du CVS anonyme.

export CVS_RSH=ssh
export CVSROOT=:pserver:anonymous@cvs.fedoraproject.org:/cvs/docs
cvs -z3 login
cvs -z3 co docs-common
cvs -z3 co <nom-de-module>

La première commande de récupération (check-out command) permet de saisir l'ensemble des fichiers communs nécessaires pour la création de documents, y compris les feuilles de style, les composants XML communs et les feuilles de style graphiques. Dans la deuxième commande, remplacez <nom-de-module> par le nom du module CVS qui vous intéresse tel que le documentation-guide. Si vous ne connaissez pas le nom du module de documentation, vous pouvez consulter la liste de tous les modules dans le CVS à l'aide des commandes suivantes :

export CVS_RSH=ssh
export CVSROOT=:pserver:anonymous@cvs.fedoraproject.org:/cvs/docs
cvs -z3 login
cvs -z3 co -c

Obtenir le plein accès au CVS

L'accès au CVS est actuellement basé sur un modèle de parrainage. Vous trouverez les informations à ce propos sur ProjetDocs/AccesCVS .

La directive la plus importante concernant le FDP CVS est que seuls les rédacteurs, les relecteurs et les gestionnaires désignés pour un document donné sont censés effectuer des modifications dans ce document.

Si un utilisateur commet des infractions, il risque de perdre son accès au CVS. Qui dit infraction dit violation de la lettre ou de l'esprit d'un accès ouvert assez souple au CVS pour les contributeurs. Les infractions comprennent et ne se limitent pas à ce qui suit, la liste ci-après étant plus ou moins en ordre de gravité (du moins grave au plus grave) :

  1. Un nombre non négligeable d'erreurs dues à l'utilisateur qui n'a pas posé des questions au préalable pour résoudre des problèmes
  2. Des modifications effectuées sur le travail des documents d'autres contributeurs sans accord préalable
  3. L'ajout de contenus illégaux, obscènes ou d'un quelconque autre contenu inacceptable
  4. Une quelconque sorte de craquage du système

Pour obtenir de l'aide avec la mise en oeuvre des procédures CVS, consultez le Documentation Guide ou CvsHelp .

Pour des informations concernant l'utilisation des branches CVS dans le FDP, référez-vous au DocsProject/CvsBranching .

La liste de diffusion pour validations (commits)

Si vous rédigez ou si vous participez à la relecture d'un projet, il est vraiment nécessaire de souscrire à la liste fedora-docs-commits.

http://www.redhat.com/mailman/listinfo/fedora-docs-commits

Savoir ce que font les autres est un aspect important d'un CVS ouvert. Les participants au projet repèrent fautes et erreurs plus rapidement et comprennent plus facilement le comment et le pourquoi des méthodes utilisées par les rédacteurs et les relecteurs.

Si vous effectuez des modifications à un fichier du module commun docs-common, vous devez répondre à votre propre message qui aura été envoyé à fedora-docs-commits, ce qui crée un message qui est expédié à la fedora-docs-list. Vous pourrez alors ajouter une explication supplémentaire, des astuces d'utilisation, et ainsi de suite.

Le rôle des documents

La partie qui suit pourrait avoir un effet sur, être affecté par, ou dupliquer des extraits du contenu du FDP Quick Start Guide [[FootNote(Le Guide de démarrage rapide FDP sera inclus dans le Guide de documentation FDP canonique.)] . Il est reproduit ici pour mémoire.

Le FDSCo gère le dépôt central de la documentation FDP. Le siège FDSCo gère la configuration globale du dépôt. Ces responsabilités sont déléguées à l'administrateur du CVS.

L'unité minimale de subdivision du dépôt est le document mais d'autres subdivisions pourraient exister aussi.

  • Chaque document a un gestionnaire, le plus souvent un membre du FDSCo qui peut accorder un accès à ce document. A l'avenir, ce gestionnaire de document sera vraisemblablement l'éditeur principal ou le rédacteur du document. Le gestionnaire est redevable pour les validations CVS de ce document faites par d'autres contributeurs, ce qui signifie que le gestionnaire doit surveiller les validations ("commits") et corriger les erreurs sans tarder.
  • A chaque document est assigné un ou plusieurs relecteurs. Un relecteur doit être quelqu'un autorisé à faire des validations CVS pour le document en question.
  • A chaque document est assigné un ou plusieurs rédacteurs. Il n'est pas nécessaire qu'un rédacteur ait l'accès à la validation CVS pour le document en question, quoique ceci soit vivement encouragé.
  • Une personne peut jouer plusieurs rôles. D'autres rôles peuvent exister aussi, tels que celui d'éditeur technique. Au fur et à mesure que la participation au FDP augmente, ces rôles peuvent devenir de plus en plus indépendants.

Pourquoi l'accès CVS en écriture est-il régi de cette façon ?

Pour des détails sur l'obtention d'un compte Fedora et la demande d'adhérence au groupe cvsdocs, référez-vous à la page Infrastructure/AccountSystem .

L'accès CVS en écriture n'est pas une cathédrale et doit être accordé dans la mesure du possible. La documentation ouverte, comme le développement de logiciels open source, est une méritocratie. Pour sécuriser l'accès au CVS en écriture, le contributeur doit démontrer qu'il est capable d'apporter de la valeur au processus. Dans le développement des logiciels open source, le contributeur démontre cette valeur en fournissant des idées qui valent quelque chose, soutenues par du code, afin d'apporter des améliorations aux logiciels. Dans la documentation ouverte, un contributeur démontre cette valeur en fournissant des idées de valeur, soutenues par de la rédaction technique, de la relecture ou de la traduction afin d'apporter des améliorations à la documentation. Des contributions bienvenues et encourageantes doivent être équilibrées par une assurance de qualité afin de réaliser les objectifs du FDP.

Le DocsProject/NewWriters explique ce que les nouveaux contributeurs doivent savoir, et le Documentation Quick Start Guide décrit le processus par lequel les contributeurs entrent dans le FDP. L'objectif du Guide de démarrage rapide est de s'assurer que n'importe quel contributeur puisse participer avec le moins de barrières possibles.

En rédigeant une SelfIntroduction et en fournissant l'échantillon d'un travail de rédaction, un contributeur apporte de la valeur au processus. L'échantillon peut être un travail original sous couvert de la licence utilisée par le FDP ou bien un travail substantiel de relecture d'un document existant. Un échantillon peut aussi être le jet d'un document ou même une SelfIntroduction bien rédigée.

Après la rédaction d'une SelfIntroduction , le contributeur peut faire une demande d'accès CVS en écriture en se servant du Fedora Accounts System . Les demandes pour un accès en écriture qui ne respecteraient pas les modalités ci-dessus pourraient être rejetées. Les membres du FDP ayant l'autorité d'approuver des demandes accordent également l'accès par le biais du Système de comptes.

Tous ceux qui ont un accès CVS et qui effectuent des validations en tant que rédacteurs, relecteurs ou traducteurs doivent souscrire au fedora-docs-list@redhat.com et au fedora-docs-commits@redhat.com. La liste des validations est notre moyen les uns par rapport aux autres d'observer, d'apprendre et de faire le suivi du travail.

Les approuveurs d'accès : Pour accorder l'accès, choisir Edit groups en bas de page. Connectez-vous si nécessaire, puis sélectionnez Edit à côté du groupe cvsdocs.

Le flux du processus

Voici un cas de figure typique d'un flux de processus :

  1. Un rédacteur poste un message sur fedora-docs-list avec son idée ou son document et exprime sa volonté de le maintenir.
  2. Si le consensus de la liste montre que la proposition est réalisable, un relecteur est attribué au rédacteur et la proposition est enregistrée sur la page Wiki DocsProject/EditorAssignments.
  3. Le rédacteur produit un premier jet et le soumet à la fedora-docs-list . Le rédacteur adresse ses requêtes ou ses questions soit à la liste de diffusion soit au relecteur qui lui a été attribué. Le FDP encourage les rédacteurs à participer aux listes de diffusion qui sont des forums actifs d'aide et de discussion.
  4. Une fois le premier jet soumis, le relecteur ouvre le nouveau bug pour le document proposé et l'ajoute au bug 129807 , qui dresse la liste de tous les documents en cours. Le document est ensuite considéré comme étant en cours.
  5. Un gestionnaire ayant les privilèges d'accorder l'accès crée un container dans le CVS pour le document en cours et accorde au rédacteur l'accès au CVS. Le gestionnaire dénommé peut assister le rédacteur et le relecteur en s'assurant que le document répond aux exigences techniques du projet.
  6. Rédacteur et relecteur se mettent d'accord sur les délais si nécessaire. Ils peuvent tous les deux valider des révisions pendant le processus éditorial soumis au FDP document lifecycle guidance.
  7. Le relecteur attribué notifie au gestionnaire désigné le moment où le document est prêt pour une dernière relecture en vue d'une publication.
  8. Une fois que rédacteur, relecteur et gestionnaire sont d'accord pour considérer que le document est complet, il est publié sur le Site officiel de la documentation .

Ce processus encourage une barrière d'entrée très souple. Le travail du rédacteur peut prendre n'importe quel format désiré (y compris le texte brut) jusqu'à une mise en forme utilisant un langage de balisage. Le balisage final sera au format DocBook XML selon les conditions du Guide de la documentation. De cette façon-là, le rédacteur et le relecteur forment une équipe avec une dimension de parrainage, dans le sens où le rédacteur apprend le DocBook XML markup (et, ce qui serait souhaitable, des normes de style aussi) pour une maintenance du document plus efficace par la suite.

Le Wiki est utilisé soit comme un outil de jet provisoire soit comme un endroit d'emplacement de publication. Le Wiki est bien adapté pour de très courts tutoriaux d'une page mais n'est pas utilisé pour maintenir des tutoriaux ou de longs guides complets. Si vous souhaitez écrire pour le Wiki, il est nécessaire de respecter les règles sur WikiEditing et sur WritingUsingTheWiki .

Les rédacteurs peuvent obtenir l'accès à des containers de documents supplémentaires en y apportant des améliorations substantielles en association avec les rédacteurs, les relecteurs et les gestionnaires. La définition de substantiel est laissée à la discrétion des relecteurs et des gestionnaires pour chaque document pour une fluidité maximale. Des contributeurs habitués peuvent être ajoutés à la liste des "power writers/editors" avec un accès à tous les autres containers.

Un rédacteur peut envoyer un mail à un relecteur pour se rétracter d'une proposition ou d'un document en cours sans préjudice. Le FDP reconnaît qu'un changement de circonstances peut parfois donner lieu à un retard dans le travail ou à un désistement sans aucun tort pour le rédacteur. Il vaut bien mieux annuler qu'abandonner simplement le travail ou disparaître de la scène. Le premier cas démontre une maturité en tant que contributeur, le deuxième et le troisième ont pour effet des impacts néfastes sur une confiance future.

Fedora est un projet dynamique qui vise à la fois à une participation ouverte et à un très haut niveau. Pour cette raison, les relecteurs et les gestionnaires pourraient demander aux rédacteurs d'apporter des améliorations aux jets avant de les accepter. Si le rédacteur ne répond pas, ou si un accord n'est pas trouvé, le relecteur peut demander à ce que la proposition ou les documents en cours soient retirés.

Le FDSCo doit approuver les retraits. Le retrait approuvé, le relecteur ferme le bug et en informe le rédacteur par mail. Une fois qu'une proposition ou un document en cours de rédaction a été retiré, d'autres rédacteurs peuvent soumettre leurs propres propositions pour le même sujet.

Les documents canoniques, tels que le Guide de la documentation ou d'autres ayant un contenu à haut risque sont soumis à un contrôle plus rigoureux.

L'utilisation efficace du CVS

ou, Comment n'ennuyer personne pendant que vous travaillez sur vos documents

  1. N'éditez pas des documents si vous n'êtes pas inscrit comme contributeur à moins qu'il s'agisse d'erreurs négligeables (orthographe, grammaire). Si vous apportez de telles modifications, tenez le contributeur officiel au courant afin d'éviter des malentendus.
  2. Si vous êtes rédacteur, assurez-vous que vous vous êtes familiarisé avec les directives concernant le langage de balisage et de style avant d'effectuer de substantielles modifications au document qui a été soumis ou qui est déjà en train d'être soumis au processus éditorial. Communiquez avec l'éditeur afin d'éviter des conflits inutiles.
  3. Respectez toujours l'étendue du document. L'ajout de redondances – telles qu'une partie du contenu d'un autre document – fait doubler le niveau requis de maintenance pour ce contenu. Efficacité avant exhaustivité : voilà pourquoi l'hyperlien existe.
Ces mêmes directives s'appliquent à la rédaction du Wiki.