FDP CVS Usage Guidelines
Usage of CVS by the FDP is subject to all overarching policies, rules and guidelines established by the Fedora Project. Users receive access to CVS, when appropriate, through the process located at the Extras CVS access page . The most important guideline for FDP CVS is that only writers, editors, and managers assigned to a particular document should be making changes to that document.
Document Roles
This section may affect, be affected by, or duplicate material in the FDP Quick Start Guide . It appears here for reference. [FIXME: Make this agree with QSG. If it doesn't it's strictly my fault.]
- The FDSC controls the overall repository of FDP documentation. The FDSC chair controls the overall configuration of the repository. [FIXME: Do we want one or more backups in case of vacation or catastrophe?]
- The repository is subdivided at least by document. Other divisions may be used as well.
- Each document has a manager, typically a FDSC member who can assign access to that document. The manager is responsible for accountable for CVS commits for that document made by the other contributors.
- Each document has one or more editors. An editor should be someone who can make CVS commits for that document.
- Each document has one or more writers. A writer need not have CVS commit access for that document.
- One person may fill more than one role. Other roles may also exist, such as that of technical reviewer. As participation in the FDP increases, these roles may separate more often.
CVS Write Access
All members of the FDSC should have CVS write access to fulfill the role of manager above.
The FDSC chair is currently the sole approver for CVS write access. As the project increases in size and scope, other approvers will be appointed, probably including some or all FDSC members. CVS write access is not a "cathedral," and should be granted wherever possible. Open documentation, like open software development, however, is a meritocracy. In order to secure CVS write access, a contributor must demonstrate that they bring value to the process. In open software development, a contributor demonstrates value by providing worthwhile ideas, backed up by code, to implement software improvements. In open documentation, a contributor demonstrates value by providing worthwhile ideas, backed up by technical writing, to implement documentation improvements.
The Documentation Quick Start Guide describes the process by which participants can enter the FDP. The goal of the Quick Start Guide is to ensure that any contributors are able to participate with as few barriers as possible. By providing technical writing samples, contributors demonstrate the value they bring to the process. These samples may be either original work, covered by the license used by the FDP, or substantial editing of existing work.
Here is a potential process flow: [FIXME: I'm being high-falutin', since I don't have any background in formally charting "process flow." I couldn't think of a better term.]
- New contributor creates bug with intent to write, is assigned an editor
- Editor negotiates a work schedule with writer
- Editor notifies manager if necessary
- Manager creates container for document in CVS repository and gives editor and writer access if necessary; ACL control fences off new container
- Editor and/or writer commit revisions during editorial process
Writers may gain access to additional document containers by providing substantial improvements to those documents in association with their writers, editors and managers. The definition of substantial is left to the editors and managers for each document, to provide maximum fluidity.
Using CVS Effectively
or, How Not to Annoy Anyone While You Work on Their Documents
Getting the Files
We recommend setting up a ~/fedora-cvs/ folder. You may then checkout one or more Fedora subprojects in this folder. For instance, if you work on documentation and software development, you would create both docs/ and extras/ subfolders. Create a local alias in ~/.bashrc to change your CVSROOT based on which folder you use. Consult our page of example scripts for more information. [FIXME: As long as you want bash that __might__ work, I can take care of this later. -- PWF]
If you have not handled CVSROOT in some other way, then edit your ~/.bashrc file. The following lines export a CVSROOT environment variable, and set cvs to use ssh for authentication to the CVS server.
export CVSROOT=:ext:pfrields@cvs.fedora.redhat.com:/cvs/docs export CVS_RSH=ssh
Open a new terminal, or source in the changes to ~/.bashrc with the following command:
. ~/.bashrc