You can send in diffs of your changes to the Cloudstack development mailing list, where your diffs will be reviewed and committed to the develop branch.
The master git branch is what Apache Cloudstack developers work with. To clone this branch, you will need to do -
git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git
You may want to pull a specific sub-branch of cloudstack-oss. To do this, you will need to first pull the cloudstack-oss branch using the git clone command above, and then, do -
git checkout <sub_branch_you_want_to_pull>
For example, 3.0.1 is the sub branch that was released to the Apache Software Foundation, so you would pull this branch using -
git checkout vpc
If you ever need to clean up temp files not tracked by git that git may complain about when pulling sub branches or changing git branches, execute the command below (but please backup any of these files if you need them since this command will wipe out any files not tracked by git!) -
git clean -d -fx ""
NOTE: If you issue the above clean command, your build/override/ directory would be removed, so you would need to re-create it. Refer to the section "How to build the cloudstack code" below to see how to create this directory and what to put into it.
Say you wish to make changes to your local sub-branch, it is always a good idea to checkout another branch from your newly created local sub-branch.
Let's summarize all the typical steps you will need to carry out, below -
Step 1) Go to the master -
git checkout master
Step 2) Either make your changes on this branch (for a simple bugfix patch), or, create a new local branch from master -
$ git checkout -b my-feature
Switched to a new branch 'my-feature'
Step 3) Confirm that you are on your new my-feature branch -
$ git branch
master
* my-feature
Step 4) Make your changes to the new my-feature branch, and git commit your changes.
Step 5) Ready your patch for submission upstream
If you did this on the master branch:
If you did this on a topic branch
Step 6) Submit your patches for review.
There are three different methods by which patches may be submitted upstream.
Other useful git commands
git stash
- Lets you stash away the changes if you don't want to commit them yet but want to change your branch
git stash apply
git stash drop
git status
Here is a workflow for non-committers to kick start feature development on GitHub:
git config reviewboard.url
https://reviews.apache.org
post-review
Committers will not be looking at your repo by default. Therefore, alert the cloudstack-dev mailing list of your work and periodically request the incremental commits you make be reviewed.
It is also best to work on feature branches rather than working directly on master even in your private fork. When the patch is ready for submission push the squashed patch through reviewboard. If the patch is sizeable and touches many projects in the repo, best to break it down into smaller chunks for easier and quicker review by multiple committers.
Holler for help on the lists if you're stuck and ever need help.
# 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"
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.
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).
Reference thread - http://markmail.org/message/j5z7dxjcqxfkfhpj
Using the git-flow git extension available at https://github.com/nvie/gitflow can reduce the number of commands/errors
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/cloudstack.git
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.
Please make your commit messages descriptive:
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: Individuals who reviewed, or link to review on review.apache.org Reported-by: whoever-reported-it, if applicable (usually this is recorded in the Jira bug) Submitted-by: give credit to other individual for any patch submission committed by you 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:
Patches encapsulated all the changes you want to make to another branch. Patches are used to communicate the changes that you want incorporated into Apache CloudStack.
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 produces a patch file for each commit in the directory (unless you specified one with -o /path/to/patch/folder).
If you've a series of commits that you want to put into a single file, try
$ git format-patch -s master --stdout > ./mycommits.patch
CloudStack currently doesn't utilize Github pull requests.
One alternative is to post the patch on Review Board.
git config reviewboard.url
https://reviews.apache.org
post-review
More materical on submitting a patch to Review Board
FIXME: This needs checking
An alternative to Review Board is to 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:
The below will configure your .gitconfig globally:
If the patch to be applied gets the commit details in the header, then use
If it's just a raw patch, then use
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.
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
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.