Adding your document to the firebird-documentation repository

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.

There are two ways to contribute: use your own fork of the repository and create pull requests to ask to add those changes to the main repository, or ask for commit rights on the main repository.

Asking for commit rights

To receive commit rights you first need a GitHub user account. If you haven't got one, register at https://github.com/. Then post a message to the firebird-docs mailing list stating your GitHub user name and asking to be added to the Firebird project. The firebird-documentation 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 (eg through a pull request), 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 will generally only have write access to the firebird-documentation repository.

Keep to the following rules:

If you have received broader access, don't ever commit to other repositories unless the people in charge of those repositories explicitly ask you to do so.
Only commit work to the firebird-documentation repository 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.
When in doubt, ask on the list, or propose the change through a pull request.

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. Refer to the Docbuilding Howto if you don't remember how to perform an git checkout.

Important

This section is not intended as a full introduction to git and GitHub. If you are not familiar with git, we highly recommend reading documentation like Getting started with GitHub and other tutorials on git on the Internet.

This section also don't cover things like using branches, however it is highly recommend to use short-lived branches for changes, especially if you are going to contribute through pull requests.

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.

It is highly recommend to update before you start working on a new document. You can do this using pull:

git pull

Once you are ready to commit, go to the firebird-documentation directory. If you use command-line git, type:

git add path/to/mydocument.xml [ even if the document already exists, this informs git that you want to add this change to your commit ]

git 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".

To make sure your local copy of the repository is up-to-date, and the history doesn't become too tangled, we recommend updating and rebasing your local branch:

git fetch

git rebase origin/master

If there are conflicts, you will need to manually fix the conflicts before you can continue.

To send your changes to the remote repository, you will need to push them:

git push

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

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

Important

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