Page History

...

Whole books could be written about this topic, and there plenty of online tutorials on the web that explain this in more detail and suggest other methods of managing changes. However, this distilled version is (hopefully) enough to get started.

To make an initial checkout of the master Lustre Git repository:

$ git clone -b master http://git.whamcloud.com/fs/lustre-dev.git lustre-master
$ cd lustre-master

Typically in git, one creates a new local branch for each change being made. The branch is created based on one of the local, pristine branches follow the main development branches, such as b1_8 or usually the master. A new local branch is usually create using checkout:

...

In order ensure that the commit description contains the correct name and email address for you, it is possible to specify this directly to Git creating or modifying the $HOME/.gitconfig file in your home directory (preferred), or in the .git/config file in the local repository. This only needs to be done one time, or once per checkout, if done in the local repository.

[user]
        name = Random J. Developer
        email = random@developer.example.org

Now all git commits in any repository will use this name/email regardless of which repository the changes are being made inuser account is used to do the modifications, if using $HOME/.gitconfig file. If you want to specify a different name or email for a specific repository, it is possible to add the same this information to the .git/config file in that specific repository.

Once you've made the change, and you're ready to create an inspection, you commit. Before you commit in git, you need to identify which files you want to commit using the "git add" command. If you haven't added any new files, and you want to commit all the files that you have changed (which is the usual case), then you can use the "-a" option to commit:

$ git commit -av

This will put you into an editor to update your commit comment, and when you save it will commit the change locally. The -v option appends the diff to the edit buffer so you can review what is about to be committed. This is very useful to verify that you are committing what you want to commit, and not changes or files that are unrelated to the current change.

It is best to commit relatively frequently to keep your changes limited to a single fix. If you notice other, unrelated, issues that need to be fixed, then it's best to put them in a separate commit on a separate branch, so they can be submitted to Gerrit independently for inspection, testing, and landing. The stash command is handy for this:

See commit comment details below.

For Lustre patches, the both the code needs to follow specific code style guidelines, as do the commit comments for each patch. In order to help maintain the uniform code style, Lustre-specific Git commit hooks should be installed in all Lustre development trees. In the top-level directory of the checked-out Lustre repository install the hooks using:

ln -sf ../../build/commit-msg .git/hooks/
ln -sf ../../build/prepare-commit-msg .git/hooks/

This will run the build/prepare-commit-msg script from the currently-checked-out Lustre tree to run the modifications through the build/checkpatch.pl script for style errors, and the build/commit-msg script afterward to verify the format of the commit message itself.

Once you've made the change, and you're ready to create an inspection, you commit. Before you commit in Git, you need to identify which new or changed files you want to commit using git add <filename>. If you haven't added any new files, and you want to commit all the files that you have changed (which is the usual case), then you can use the -a option to commit:

$ git commit -av

This will put you into an editor to update your commit comment, and when you save it will commit the change locally. The -v option appends the diff to the edit buffer so you can review what is about to be committed. This is very useful to verify that you are committing what you want to commit, and not changes or files that are unrelated to the current change.

It is best to commit relatively frequently to keep your changes limited to a single fix. If you notice other, unrelated, issues that need to be fixed, then it's best to put them in a separate commit on a separate branch, so they can be submitted to Gerrit independently for inspection, testing, and landing. The stash command is handy for this:

# While fixing a bug you

# While fixing a bug you notice something evil that must be fixed.
# First set your current work aside:
$ git stash

# Next go create a new branch and purge the ugliness you just discovered:
$ git checkout -b my-eyes-are-bleeding master
\{ fix ugliness \}
$ git commit -av

# Now go back to what you were working on:
$ git checkout my-brilliant-idea
$ git stash pop

...

Having good commit comments helps everyone that is working on the code. See Commit Comments for a detailed description of the commit comment style. If your commit does not include the Change-Id: line as described below, the patch will be automatically rejected at submission time.

Sample Commit message:

LU-000nnn component: short description of change under 6462 columns

A more detailed explanation of the change being made.  This can be
as detailed as you'd like, possibly several paragraphs in length.

Please provide a detailed explanation of what problem was solved,
a good high-level description of how it was solved, and which
parts of the code were affected (including function names as
needed, for easier searching).  Wrap lines at 70 columns or less.

Signed-off-by: Random J Developer <random@developer.example.org>
Change-Id: Ica9ed1612eab0c4673dee088f8b441d806c64932

...

It is possible to push a series of dependent commits from a local branch in this same way, and each one will create a separate change in Gerrit. Patch series should be used to split complex code changes that are implementing a single larger feature into chunks that are easier to understand. These changes will be dependent on each other, so if one patch needs needs to be refreshed after an inspection it will cause all of the later patches to be refreshed after an inspection it will cause all of the later patches to be refreshed also. That will clear all of the inspections and restart testing on all of the patchesalso. That will clear all of the inspections and restart testing on all of the patches.

Patch series should not be used for code that was written and then had a series of bug fixes applied to it after local testing. The later (local) bug fixes should be squashed into the original change before submission. Note that each patch in a series must build and test properly before it can be landed, so intermediate bugs or compile warnings are not allowed.

If you have a series of independent commits to be reviewed, each one should be in a separate local branch and pushed separately to Gerrit. This allows the patches to be inspected, tested, and landed independently, and will avoid the overhead and delay of repeatedly inspecting, building, and testing patches that are only refreshed because of an earlier (unrelated) patch in a series being modified.

...

When the patch has been pushed to the Gerrit review repository, it will print a URL for that change set that should be added to the bug for this change in Jira ticket for tracking.

All patches submitted to Gerrit will be built automatically by Jenkins (formerly Hudson) with a number of configurations. Currently for the master branch this includes RHEL6 i686/x86_64 client/server, RHEL5 i686/x86_64 client/server, Ubuntu 10.04 x86_64 client, and SLES11 SP1 x86_64 client. The success/failure of these builds will be posted to the change in Gerrit.

...