Overview and initial housekeepingThis is still a work in progress - don't trust it yet!

On May 25th the canonical repository for CloudStack will move to a ASF-hosted repository located here:

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

For folks who already have existing local repositories you will have two options: 

Replace your 'origin' with the new origin as your default remote

or

Add a new remote to your existing configuration

Replacing origin with the new origin as your default remote.

To do this you first need to change directory into your local repo and then execute the following commands:$ git remote rm originThe above will remove the existing remote you have defined$ git remote add origin https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.gitThat's it - when you pull or push now you'll be doing so with the new repo. 

Adding a new remote to your existing configuration

For a variety of reasons you might want to have more than one remote, perhaps you want to maintain your own fork - or you have your own repo tracking larger changes, or just because you can. That's trivially easy to handle. $ git remote add asf https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.gitNow it becomes incumbent upon you to decide where you are pushing what: 

If for example you are in the master branch and wish to push your changes to the master branch on the asf repository you'd then execute the following example: $ git push asf master

A word on pushes

If you have branches which are mutually exclusive in your remotes - you want to take special notice of this section. 

Git has a configuration item that controls what gets pushed where - and the default has changed over time. You should consider setting this. 

The configuration is push.default, and you can configure it by using: $ git config push.default $optionThe options are: 

• nothing : Do not push anything
• matching : Push all matching branches
• tracking : Push the current branch to whatever it is tracking
• current : Push the current branch

If you are using tracking, and you've added a new origin, you may want to delete your local branch and pull from the new remote. However, you shouldn't be afraid - it's a revision control system and most things can be undone. However do take note of the section 'Never use the --force' below

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. Because of legal requirements, patches must pass through the bugtracker or the mailing list, with the current preference being the mailing list. 

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

Branches

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. The first line should contain the bug or feature that you are working on. Please err on the side of verbosity. Also, it's important to note that the diff will provide an easy way to see what has changed - the more important element in a commit message is the why you made the changes the way you did. For more discussion on this, please take a look at: 

http://www.pyinstaller.org/wiki/Development/CommitMessages

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).

Sending patches

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.patchHow 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.