Adding your document to the manual module

Asking for commit rights
Dos and don'ts if you have received commit rights
Committing your work

When your doc is finished, and you have verified that it builds correctly, you want it added to the manual module. If this is your first contribution to the documentation project you'll probably have agreed with the coordinators that you first submit it to them for review, or that you temporarily put up the HTML version on a website so that it can be discussed on the list. After that – and maybe after some corrections are made – the document can be committed to the module. If you have commit rights you can do this yourself; if not, one of the coordinators will do it for you.

Asking for commit rights

To receive commit rights you first need a SourceForge user account. If you haven't got one, register at http://sourceforge.net/account/register.php. Then post a message to the firebird-docs mailing list stating your SF user name and asking to be added to the Firebird project. The manual subproject leader and several Firebird project admins follow the list; they will consider your request. As a general rule you should ask for commit rights after your first contribution, because the people who decide on your request need something to go by.

The following phrases currently all mean the same, by the way:

Being a project member.
Having commit rights.
Having read-write access to the repository.

Dos and don'ts if you have received commit rights

Once you are accepted as a project member, you have write access to the entire Firebird repository, not only to the manual module. There is no technical barrier to keep you from committing changes to other modules – the firebird2 core module for instance, or even the CVSROOT module where important project information is stored.

You may already have guessed that this is NOT the idea. Keep to the following rules:

Don't ever commit to other modules unless the people in charge of those modules explicitly ask you to do so.
Only commit work to the manual module if it concerns a task assigned to you. Even then, it's good practice to announce your changes and additions on the mailing list first, so the other doccers have a chance to comment on it. After all, this is a collective effort.
If you think a new document or directory should be added, don't just create and commit it, but propose it on the list.

In practice, things may be a bit more relaxed than stated here, especially where it concerns your own tasks. We don't want you to feel unfree and you certainly shouldn't get the feeling that you have to ask permission for every minor change you make. But we do want you to act responsibly, and we want to know from each other what we are doing. Besides, keeping in touch with each other is often inspirational. Together we can make this thing work!

Committing your work

Even if you are a project member, you can only commit changes from a local copy if it was checked out with your SF login name. If you're still working with a copy you've checked out anonymously you must first make a fresh SSH checkout, and then re-apply your changes and commit them. Refer to the Docbuilding Howto if you don't remember how to perform an SSH checkout.

If some time has passed since your last checkout or update, perform an update before committing. This will get your local copy in sync with the repository and reduce the possibility of conflicts.

Once you are ready to commit, go to the manual directory. If you use command-line CVS, type:

cvs update -d [ only if you want to update first ]

cvs add path/to/mydocument.xml [ only if it concerns a new document not yet in CVS ]

cvs commit -m "Short informational message here"

After the -m, and within quotes, you type a short message about this commit, e.g. "Added new functions to API Reference" or "Errors in isql tutorial fixed".

Give your SF password when prompted, and all the changes you have made – including those in subdirectories – will be committed. Your CVS client knows which server to contact; this and other information is stored in the CVS subdirectories that were created upon checkout.

If you use another CVS client, refer to its documentation.

Important

After adding a new document, you must still perform a separate commit. This goes for command-line CVS and most (if not all) other CVS clients.