README.GIT

*WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING*
The Git tree may not always have code which can currently be built.
While every effort is made to keep the head of the tree buildable,
you may at any time find yourself between commits and hence have a tree
which does not build, or worse, causes more serious problems!

Do not use the Git tree unless you know what you're doing.

Git checkouts do not include files generated by autoconf. You can
run regen.sh (at the top level) to create these files. You will need
to have autoconf and automake installed on your system.

Summary
-------

Browse:  http://git.openafs.org/
Clone:   git clone git://git.openafs.org/openafs.git

Step-by-step
------------

1. Obtain the Git software. If you are using a system with a standard
   software repository, Git may already be available as a package named
   something like git or git-core.  Otherwise, go to http://git-scm.com/

2. Run the command:

   % git clone git://git.openafs.org/openafs.git

   This will download the full repository and leave a checked-out tree in
   a subdirectory of the current directory named openafs. The repository
   itself is in the .git subdirectory of that directory.

   WARNING: The repository is approximately 60MiB currently and will only
   grow, so it may take some time to download the first time over a slow
   network connection.

3. Generate the additional required files:

   % cd openafs
   % ./regen.sh

The current development series is in the branch named master. The stable
releases are on separate branches named something like
openafs-stable_<version> with a separate branch for each major stable
release series. Use git branch -a to see a full list of branches.

OpenAFS uses the Gerrit code review system to review and merge all changes
to OpenAFS. More details are at:

    http://wiki.openafs.org/GitDevelopers/

including more detailed Git instructions.

It's by far preferred to use Gerrit to submit code changes, but if you
can't for whatever reason, you can instead open a bug and submit a patch
that way. Do this by sending mail to openafs-bugs@openafs.org with the
patch attached. But please use Gerrit if you can; patches sent in as bugs
will have to be forwarded to Gerrit by someone else, and it's easier for
everyone if you can enter them into Gerrit yourself.

Backport policy
------------
All patches should land on master first, unless the patch fixes a bug
that only exists in the stable branch.

Once a patch has been accepted into master, anyone can propose
backports to stable branches.

When cherry-picking a commit from another branch, please append a
"cherry picked from" section in your commit message. You'll also need
a separate Change-ID for Gerrit to recognize this as a separate
change. One workflow to do this:

1) Use "git cherry-pick -ex" to pick your commits onto another branch.
   The -x option will append the appropriate "cherry picked from"
   message, and the -e option will open your editor for you to edit
   the commit message.
2) In your editor, delete the existing Change-ID line. Save and quit.
3) Run "git commit --amend", saving and quitting again. Git will run
   the commit hook and generate a new Change-ID for Gerrit.