You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Using Git in CloudStack

Git Config

# Set the name of the user for all git instances on the system
git config --global user.name "Firstname Lastname"
# Set the email-address of the user for all git instances on the system
git config --global user.email "your_email@youremail.com"

Committer workflow

Your own work can be committed easily - git push is all you need. Be mindful of the branch that you are working in and ensuring that it is the current branch for development. It might also behoove you to make changes to multiple branches (e.g. current development and head). Please be mindful that just because you have commit privileges does not relieve you of the obligation to develop in the open, which means communication on the cloudstack-dev list. 

Handling patches

As a committer one of your responsibilities is to review and commit patches from others. The patches must pass through the bugtracker or the mailing list so they can be tracked.

Patches should be applied via git-am (in other words, don't just use a diff, it records no author information). 

Non-committer workflow

Cloning

First you need to have a copy of the source - you should be able to acquire that by cloning the repo:

$ git clone https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git

Branch

The CloudStack repo has multiple branches, some version specific, you'll need to figure out which one you need to work with, but we'll make the assumption that master is OK for this purpose. Now, when you are ready to actually hack on CloudStack you should create your own topic branch locally. Lets say you wish to work on a specific bug, then you should work on that bug (and only that bug) in its own local branch (known as a topic branch), and you should use a descriptive name for it.

Suppose you are working on bug CS-15081 - you'd create a branch by the same name: $ git checkout -b CS-15081   (this both creates the branch and switches to using it) 

Now you can make your changes - and once done submit patches. 

Commit Messages

Please make your commit messages descriptive:

  • Commit messages should be clear, concise and provide a reasonable summary to give an indication of what was changed and why.
  • Commit messages should provide enough information to enable a third party to decide if the change is relevant to them and if they need to read the change itself.
  • Avoid committing several unrelated changes in one go. It makes merging difficult, and also makes it harder to determine which change is the culprit if a bug crops up.
  • Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made. In the case of documentation files, it can make the job of the translation teams more complicated, as it becomes difficult for them to determine exactly what content changes need to be translated.
  • Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small, related groups of files) with tailored commit messages.

A good commit message should look like this:

Header line: Explain the commit in one line

Body of commit message is a few lines of text, explaining things in more detail,

possibly giving some background about the issue being fixed, etc etc. Use bullets if possible:
 - Line 1
 - Line 2 etc.
 * Start works too, instead of -

The body of the commit message can be several paragraphs, and please do proper word-wrap

and keep columns shorter than about 80 characters or so. That way "git log" will show things

nicely even when it's indented.

Reviewed-by: Person or link to review on review.apache.org
Reported-by: whoever-reported-it, if applicable
Signed-off-by: Your Name <youremail@yourhost.com>

Note that there exists a git hook to prepare a commit form for you, located at tools/git/prepare-commit-msg. One simply needs to link to it in order to use it:

ln -s ../../tools/git/prepare-commit-msg .git/hooks/prepare-commit-msg

Please use a logical prefix, which should be:

  • CLOUDSTACK-XXX-bug-id prefix: Explain the bugfix in one line; This is for only bug fixes.
  • Maven: If this changes the build system
  • Doc: If this is doc related change
  • awsapi: If the code changes several things inside a subproject, use artifactId sans the cloud- prefix such as: plugin-netapp; this should be lowercase
  • NameOfTheClass: If this patch purely changes to ThisClass, this should be CamelCase

Patches

Creating patches

Patches should be created with git-format-patch - and you should specifically be basing that against the branch you are targeting for inclusion, so for instance using our above example from the CS-15081 branch we'd run:

$ git format-patch -s master

The above would produce a patch file in the directory (unless you specified one with -o /path/to/patch/folder).

Sending patches

How to Submit Patch to Review Board

FIXME: This needs checking

You can now email that patch to the cloudstack-dev mailing list with [PATCH] in the subject line.

You should expect some feedback on your patch within a week. If you don't receive any - please reply to the original message to make sure folks didn't miss it.

Sending patches can be done with the git send-email tool:

$ git send-email your-newly-generated.patch

How to setup git-send-email tool:

  • yum install git-email or sudo apt-get install git-email (this will install git send-email tool)

The below will configure your .gitconfig globally:

  • git config --global sendemail.smtpserver <smtp-server-name>
  • git config --global sendemail.to <emailing-list>
  • git config --global sendemail.from <email-id>

Words of wisdom

Never use the --force

Git assumes that if you have commit privileges that you are to be trusted, and generally this is a good thing. However, occasionally people are lured by the dark side of the force and when something doesn't merge cleanly, or their push doesn't work - they are tempted to whip out the --force and make it work. PLEASE NEVER DO THIS. It's is almost universally wrong. Please tell us about your problem on cloudstack-dev and let us help you fix it. 

Line endings

The coding standard for CloudStack says that unix line endings (LF) are used instead of CRLF (Windows line endings). You should set your editor and git configuration to behave properly. 

For more information: 

http://help.github.com/line-endings/

http://git-scm.com/docs/git-config

Fixing things for folks

In short, please don't. If non-committers have a patch 95% of the way - comment and tell them what is necessary to make the patch acceptable. Let them fix their own patch and resubmit. Yes you can probably fix things more quickly, but it's important for community growth (both in number and experience) that folks do this themselves. 

  • No labels