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
You must install the  and   packages  to use this project. For some older systems like RHEL or CentOS 5, you may need to use  instead of.

Install the  and   packages with  : su -c 'yum install git-all publican-fedora'

Create your global  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
To get a copy of a module, in this example the  project for the source of the Fedora Installation Guide:

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

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

Using the Right Branch
We use  branches to separate releases of any guides that are tied to specific Fedora releases. For instance, the Installation Guide has multiple active versions at any one time. Right now, those versions are, , and. (Releases for will be on the main or "master" branch.)

To see all the available branches from the origin, do this: git branch -r You'll see a list that may look like this: origin/HEAD origin/f origin/f origin/master

Before you start working, make sure you are on the proper branch (f, f, or master) using one of these commands: cd install-guide git checkout -b --track So if you want to work on the f branch, use this command: git checkout -b f --track origin/f

Make a personal branch
The  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" and move onto it to do your actual work: cd install-guide git checkout -b mywork

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

Make changes
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  command. If you need to delete files, use the  command. To rename or relocate a file, use the  command.

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 (this example is using the original "en-US" language): publican build --formats=xml --langs=en-US

Stage the changes
The  command tells git that it should stage specific changes you make. Staged changes are the changes that will be recorded in the next commit. You can stage changes from more than one file at a time, but you should make sure these changes are related. Don't stage changes together that have nothing to do with each other. It's OK to make several commits, and usually a better idea to do so if you're unsure. git add en-US/my-changed-file1 en-US/my-changed-file2

Commit the changes
Once you're ready to commit your changes, use the  command. git commit -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.

Sending changes if you're not authorized
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. Then you can email those patch files to [mailto:fedora-docs-list@redhat.com the maintainers].

Merging and pushing if you're authorized
If you mistakenly used  for cloning instead of , you can fix that by editing the   file before pushing. Look for the "origin" section and edit the URL, replacing  with.

Merging
Switch from your private branch to the branch you are working in, most likely master

git checkout master

Merge the changes from your private branch (named 'mywork' in this case) to master:

git merge mywork

Pushing
You should be able to push your changes to the remote repository by running:

git push

Other References

 * http://book.git-scm.com -- the best user-friendly git documentation, from the git project itself
 * http://www.gitcasts.com
 * http://excess.org/article/2008/07/ogre-git-tutorial/ -- complete tutorial that includes an explanation of SCM (source code management)