Docs Project work using git

The Documentation Project produces documentation written in DocBook XML. Earlier documentation used a CVS instance for collaboration. The DocBook XML files are now maintained in git repositories, which provide better features and future proofing. DocBook XML documentation can be built into HTML and other formats for use on the Web and in Fedora itself.

You can help maintain content on the wiki, but it is also helpful to know how to make changes in this repository as well. The following guide will show you, step by step, how to do that.

Setting Up

Install packages
You will need the git-all and publican-fedora packages installed.

Run this command to install them, if not already done:

su -c 'yum install git-all publican-fedora'

Then set up your global git configuration:

git config --global user.name 'John Doe'
git config --global user.email 'jdoe@example.com'
git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

Getting a Copy of the Files

mkdir projects
cd projects
git clone git://git.fedoraproject.org/git/install-guide

A copy of the files from this repository are now in the install-guide directory in your current working directory.

Locally or remotely writable
The git command above produces a repository where you can make changes locally, but not back at the remote source (origin). If you're a user of this repository authorized to write changes, use git+ssh:// instead of git:// in the git clone command above.

Making Changes

The git application uses branches in a novel way, to allow you to keep your work separated from the files that you just retrieved. You should always make a branch of the files and do your work there. Then after you've done appropriate testing, you can merge those changes into the branch you retrieved and send them to the maintainers via email, or (if you have access) push them back to the repository here.

First, make a branch called "mywork":

cd install-guide
git branch mywork

Then move onto that branch to do your actual work:

git checkout mywork

(Note this doesn't retrieve files, it puts you on the new mywork branch you created. To check that you've moved branches, you can use the git branch command again:

git branch

Now make a desired change. Remember that you don't want to make a bunch of changes at one time -- make one meaningful change (like cleaning up one file, or cleaning up one issue that happens in a number of files) at a time.

To check the status of your branch (how it differs from the last recorded change), run the git status command. If you need to add or delete files, use the git add or git rm commands. To rename or relocate a file, use the git mv command.

Once you've finished making a meaningful change, commit it.

git commit -a -m 'Some short message about the commit'

The commit goes to your local branch, not back up to the server as in some other version control systems.

Once you have finished with all the changes, DOUBLE CHECK THEM! Don't go any further until the changes you made to the Release Notes produce a fully working document. Run a validation test to check:

make test

Sending Back Changes (Unauthorized Version)

If everything works, you can email your changes back to the maintainers even if you're not authorized to write to the repository:

git-format-patch -o /tmp/mywork origin

This puts a series of patch files in the new directory /tmp/mywork. Then you can email those patch files to the maintainers.

Merging and Pushing (Authorized Version)

If you're authorized, you can send your commits back to the repository. To push the results up to the repository here at Fedora Hosted:

git push origin/master

If you mistakenly used git:// for cloning instead of git+ssh://, you can fix that by editing the .git/config file before pushing.

From the author
I'm just learning git, so the use of the master branch above may not be the best practice. Input gratefully accepted from more experienced git users.