Docs Project CVS usage

FDP CVS Usage Guidelines

Introduction

The Concurrent Versions System, or CVS, is software that allows people to cooperatively work on a set of files, such as in a development or documentation project.

You can use ViewCVS to browse the Fedora Documentation CVS repository.

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 through the Fedora account system .

You can read more about CVS at one of the following sites:

• CVS home page
• GNU Project - CVS

Anonymous CVS

You can get files from the Fedora Documentation Project using anonymous CVS.

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

The first check-out command grabs the set of common files you need to build the documents, including stylesheets, common XML components, and stylesheet images. In the second check-out command, replace <name-of-module> with the name of the CVS module you are interested in, such as documentation-guide. If you do not know the name of the document module, you can see a listing of all modules in CVS with these commands:

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

Gaining Full CVS Access

CVS access is now under a sponsorship model, and details are found at DocsProject/CVSAccess .

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.

Users risk losing access to CVS if they commit infractions. An infraction is a violation of the letter or spirit of low-barrier, open CVS access for contributors. Infractions include but are not limited to the following, listed somewhat in order of severity (least to most):

1. Making lots of mistakes because the user has not resolved questions first
2. Making edits of other people's documents without prior agreement
3. Putting illegal, obscene, or otherwise objectionable material in CVS
4. System cracking of any kind

For help with hands-on CVS procedures, consult the Documentation Guide or CvsHelp .

For information on using CVS branches in FDP, refer to DocsProject/CvsBranching .

The commits mailing list

If you are writing or editing for the project, it is truly necessary to subscribe to the fedora-docs-commits list.

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

An important part of having an open CVS is seeing what everyone is doing. Participants catch mistakes more quickly, and they more easily learn how and why writers and editors do as they do.

If you make a change to a file in the common module docs-common, you must reply to your own message that went to fedora-docs-commits, which makes a message that goes to fedora-docs-list. You can then add in additional explanation, usage tips, and so forth.

Document Roles

This section may affect, be affected by, or duplicate material in the FDP Quick Start Guide . It appears here for reference.

The Docs Project controls the overall repository of Fedora Docs Project documentation. The Docs Project Lead controls the overall configuration of the repository. The CVS administrator is delegated these responsibilities.

The repository is subdivided at least by document, and may use other divisions as well.

• Each document has a manager, typically a Fedora Docs Project member, who can assign access to that document. In the future, this document manager will likely be the main editor or writer for the document. The manager is accountable for CVS commits for that document made by the other contributors, meaning the manager needs to watch commits and fix mistakes early.
• 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, but is encouraged to have it.
• One person may fill more than one role. Other roles may also exist, such as that of technical reviewer. As participation in the Fedora Docs Project increases, these roles may separate more often.

Why is CVS Write Access Governed in This Way?

For details on getting a Fedora account and requesting to join the cvsdocs group, refer to the Infrastructure/AccountSystem page.

CVS write access is not a cathedral, and should be granted wherever possible. Open documentation, like open software development, is a meritocracy. 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, editing, or translating, to implement documentation improvements. Encouraging and welcoming contribution must be balanced with quality assurance to fulfill the goals of the FDP.

The DocsProject/NewWriters explains what new contributors need to know, and Documentation Quick Start Guide describes the process by which participants 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 making a SelfIntroduction and providing a writing sample, a contributor brings value to the process. The sample may be either original work, covered by the license used by the FDP, or substantial editing of existing work. A sample might even be a draft document, or even a well-written SelfIntroduction .

After doing a SelfIntroduction , the contributor can apply for CVS write access using the Fedora Accounts System . Applications for write access that do not follow from the above process may be rejected. FDP members with approval authority grant access through the Accounts System as well.

Anyone who has CVS access and makes commits as a writer, editor, or translator must be subscribed to both fedora-docs-list@redhat.com and fedora-docs-commits@redhat.com. The commits list is how we watch out for, learn from, and keep track of each other.

Access Approvers: To grant access, select Edit groups at the bottom of the page. Log in if required, and then select Edit next to the cvsdocs group.

Process Flow

Here is a potential process flow:

1. A writer posts to fedora-docs-list with an idea or document, and the willingness to maintain it.
   • New contributors should make a SelfIntroduction .
2. If the consensus of the list is that the proposal is feasible, then the writer is assigned an editor and the proposal is registered on the the DocsProject/EditorAssignments Wiki page.
3. The writer produces an initial draft and submits it to fedora-docs-list . The writer directs any queries or questions either to the mailing list, or the assigned editor. The FDP encourages writers to participate on the mailing list, which is an active forum for help and debate.
4. Once an initial draft has been submitted, the editor opens a new bug for the proposed document and adds it to bug 129807 , which list all documents in progress. The document is then considered in progress.
5. A manager with access-granting privilege creates a container in CVS for the document in progress, and gives the writer CVS access. The assigned manager can assist the writer and editor in ensuring that the document is compatible with the technical requirements of the Project.
6. The editor negotiates any work schedule with the writer if necessary. Both may commit revisions during the editorial process, subject to the FDP document lifecycle guidance.
7. The assigned editor notifies the assigned manager when the document is ready for final review for publication.
8. Once the writer, editor and manager agree that the document is complete, it is published on the official Documentation Website .

This process promotes an extremely low barrier to entry. The writer's work may be in any format desired (including plain text) up to the point of final markup, as agreed upon by the editor. The final markup will be in DocBook XML as required in the Documentation Guide. In this way, the writer and the editor form a team with a mentorship aspect, so that the writer learns DocBook XML markup (and hopefully style as well) for more effective document maintenance later.

The Wiki is used as either an interim drafting tool or as a final publishing location. The Wiki is good for very short, one-page how-to pieces, but is not used for writing and maintaining full lengthy tutorials or guides. If you want to author in the Wiki, you need to use the rules at WikiEditing and WritingUsingTheWiki .

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. Regular contributors may be added to a list of "power writers/editors" with access to all other containers.

A writer may e-mail their editor and withdraw proposals or documents in progress without any prejudice. The FDP recognizes that sometimes changing circumstances result in work delays or cancellations, through no fault of the writer. It is far better to cancel than to just drop the work or disappear. The first shows maturity as a contributor, the second and third make people not willing to trust you in the future.

Fedora is a dynamic project that aims for both open participation and high standards. For these reasons, editors and managers may ask writers to amend their drafts before accepting them. If the writer does not respond, or no agreement can be reached, then the editor may request that the proposal or documents in progress be withdrawn.

The FDSCo must approve withdrawals. Once a withdrawal is approved, the editor then closes the bug and informs the writer by e-mail. Once a proposal or document in progress has been withdrawn, other writers may submit their own proposals for the same subject.

Canonical documents, such as the Documentation Guide, or other high-risk content areas are somewhat more closely controlled.

Using CVS Effectively

or, How Not to Annoy Anyone While You Work on Documents

1. Do not edit documents on which you are not a contributor unless correcting trivial errors (spelling, grammar). If you make such an edit, notify the official contributors to avoid misunderstandings.
2. If you are a writer, make sure you are familiar with markup and style guidelines before you make any substantial changes to a document that is or has been in the editorial process already. Communicate with the editor to avoid any unnecessary conflicts.
3. Always respect the scope of the document. Adding redundancy -- such as material covered in another document -- at least doubles the amount of maintenance required for that redundant material. Efficiency before comprehensiveness: this is why the hyperlink exists.

These same guidelines apply to writing in the Wiki.