Contributing to OpenRasta
OpenRasta is an Open Source project, and like any project, there are some rules around how we collaborate.
- core.autocrlf=false
- Feature branches prefixed with f/
- Pull requests required to move to master
- Copyright license agreement required for large contributions
We use github, which is a great collaboration platform. The ease with which one can branch code may sometimes lead to very muddied timelines, and this makes accepting pull requests very, very difficult.
So here are some guidelines on how to keep your repositories clean and make the project's life easier.
Please set your git to use core.autocrlf to false before cloning the repository, this is very very important, if you fail doing that we won't accept a pull request.
If you provide bug fixes, please provide a unit test that reproduces the issue and fail if the code is not changed. If you don't provide unit tests, we'll have to write them before accepting your pull request, increasing the time it takes for everyone to have their pull requests processed.
Unit tests are usually grouped logically, try to add your test scenario alongside existing tests. Tests usually follow a pattern by which given and when are executed in the constructor, and one test method equals one assertion, please try to follow that pattern. We do not use the Assert class but the Should extension methods, please follow that convention too.
Note that unit tests are for functional bugs, if you're correcting a spelling mistake you do not need to provide them. In doubt, ask the development mailing list (http://groups.google.com/group/openwrap-devel).
Please do not reformat code when submitting a patch, those make patches difficult to process and read.
Do follow the code conventions that are already in place in the code you're modifying. ReSharper rules ship with most package source code, please make sure you use them (ReSharper menu > Options > Common > Code Style Sharing > Shared across the team, per solution).
The first step is to fork your chosen package, by going to the package address (say, http://github.com/openrasta/openrasta-core/), and clicking the Fork button.
This will create your own copy of the code. Next, you need to clone your new repository.
c:\src> git clone git@github.com:yourUsername/openrasta-core.git
You'll now have a local repository, with your github fork called origin. It contains a branch called master that starts at the point you did your fork. In other words, it contains everything that was in the official repository up to the point at which you forked the project.
To continue integrating changes from upstream (a.k.a. from the official repository), you need to pull the changes back onto your master branch on a regular basis (and certainly every time you want to submit a pull request).
As Git doesn't have one central repository, it can have as many as you want, we need a way to integrate the official changes back into your fork, so you can update your repository to the latest and greatest.
Your fork of the project is by default configured as a remote called origin, and this is where you will be submitting code.
To see all your remotes (the repositories you can get updates from and write code to), you can use the following:
c:\src\openrasta-core> git remote -v
origin git@github.com:yourUsername/openrasta-core.git (fetch)
origin git@github.com:yourUsername/openrasta-core.git (push)
We need to add the original project's repository to your remotes.
c:\src\openrasta-core> git remote add upstream http://github.com/openrasta/openrasta-core.git
You now have two remotes, origin where you can write code to, and upstream, where you can't.
Whenever you want to put your repository back in sync with the official one, you can pull the changes from upstream and then push the changes back into origin.
c:\src\openrasta-core> git pull upstream master
c:\src\openrasta-core> git push origin master
This will have put your repository back in sync for the master branch.
Git is heavily branch-oriented, and unlike system like SVN, branches are actually very quick and easy to use, so the whole OpenRasta development model is based around them.
The master is where the current release of any of the packages lives, and probably where you will be doing changes you want to send back. To make things simple, the best thing you can do is to ensure that you never write anything to master, aka you never commit any code to your master. This will let you take in changes much more easily from the upstream project.
When you decide to work on a bug (or a feature), start by creating a new branch specifically for this work (and only for this work) and prefix it with "f/" for feature branch.
c:\src\openrasta-core> git checkout -b f/bug_112_description
This will switch from the master branch on your repository (the one that should be in sync with the master branch in your github fork and with the upstream project) to a new branch called bug_112_description. Try to be descriptive in how you call the branch, either call it the name of a new feature or specifically the bug number.
(git checkout -b new_branch_name is a shorthand for git branch new_branch_name; git checkout new_branch_name)
You can now start changing your files, git add, git commit, rinse repeat until you are happy that you have fixed the bug.
Once you're happy, there's a few things you ought to do. First and foremost, if you have a lot of commits along the lines of "Woops, forgot a file" or "Removing unnecessary things", those do not add much value to the project, and git provides you with an excellent way to remove those superfluous commits by squashing them together.
Ideally each commit should leave code in a compilable state and the tests should all pass. This makes identifying issues due to merges much easier.
To see your recent checkins, you can use git log. Let's take an example:
c:\src\openrasta-core> git log
commit: 4d1536f415eabdb5a3dedc91dedffbb9f14a1847
Author: YourUserName
Date: Tue May 10 10:30:00 2011
Forgot some files...
commit: 1d8480ef205ef6af845670daf6a8922f1d2dfdd9
Author: YourUserName
Date: Tue May 10 10:30:00 2011
Fixing improper use of GC.GarbageCollect();
As you can see, the second commit (the "Forgot some files...") is quite superfluous, and it would be much better to merge it with the previous one.
Enter the world of git rebase --interactive. First, if you've not set your editor to some graphical text editor, I'd advise you to do that now (see Jeremy Skinner's guide to contributing to MvcContrib, most of it applies here).
Now find the last commit you're happy with (here it would be the "Fixing..." one), copy it's commit ID, and ask for an interactive rebase:
c:\src\openrasta-core> git rebase 1d8480ef205ef6af845670daf6a8922f1d2dfdd9 --interactive
This will pop up a window showing you the following (and some help, which we'll ignore):
pick 4d1536f fixes the system repository coming from the shell not going to the right place (woops)
# Rebase 1d8480e..4d1536f onto 1d8480e
#
# Commands:
# ...
The help is pretty self-explanatory, but in this case, you want to replace the text pick by the text squash, which will remove that commit and meld it with the previous one (the one we were happy with).
Save the file and close the editor, git will do it's magic and leave you with a nice clean branch, ready to issue a pull request.
One last thing that would usually be very useful is for you to make sure any pull request you submit is on the HEAD (aka the last commit) of the master branch of the upstream repository. You already know how to do that, but I'll repeat it just in case.
c:\src\openrasta-core> git checkout master
c:\src\openrasta-core> git pull upstream master
No need to pull from origin master as you should not be committing anything to master for the reasons we've explained before.
Now that your master branch is up to date, it may now be a couple of commits ahead of the branch you've created for the pull requests. You ought to rebase your changes, aka to re-apply the commits you've done to fix the issue on top of the latest upstream. Otherwise we end up with merges that leaves the history non-linear, which we don't like too much of.
It sounds complicated but in practice it's dead easy.
# switch back to the bug fixing branch
c:\src\openrasta-core> git checkout f/bug_112_description
# rebase on top of master
c:\src\openrasta-core> git rebase origin master
This should be a very painless excercise if you've not waited too long. Resolve any conflicts if you find some, otherwise you're ready to submit.
First, push the branch to your github repository.
c:\src\openrasta-core> git push origin f/bug_112_description
Now you need to log-in to github, click on Pull Request, and follow the instructions on screen.
OpenRasta is mostly under Caffeine IT's Copyright. When someone contributes some code, we classify that code in two categories, trivial and non-trivial.
A trivial contribution is any patch or addition to the code-base that does not exceed 15 lines of code, and for which the code's complexity is considered trivial, a.k.a. any other skilled developer, faced with the same issue, would've found the same fix.
If you wish to submit work that goes above and beyond those trivial fixes, you need to sign and return a Copyright License Agreement that gives us the right to redistribute your work. If you don't sign one, we won't accept the code, under any circumstance.
Next: FAQs