Contributing

dmclain edited this page Jun 27, 2011 · 2 revisions
Clone this wiki locally

So you want to contribute to Armstrong? You're at the right place.

All development on Armstrong and its various packages happens on GitHub. The code in the armstrong repositories should always remain in a stable state. Actual bleeding edge development happens in forks, with the final code being sent back as Pull Requests.

Discussing your idea

The best place for real-time discussion is the #armstrongcms IRC channel on Freenode. Most of the core contributors idle in this channel, but a lot of them use IRC bouncers to always stay connected. Just because someone's in there at 3 AM doesn't mean they'll respond (but they might!)

You can also talk about your idea on the Google Group. That's is the place of record, so be sure to bring it up there.

All that said, code speaks loudest. Ideas explained in the description of pull requests are always better than ideas in an email. We can't run and test emails.

Feature Branches

You should always develop your code in a feature branch. The master branches across forks should be in sync with the master branch in the main repository.

If you're working on multiple features at one time, it's a good idea to create an integration branch. This should be kept up to date with all of the feature branches so they can be tested as one.

Pull Requests

Open a pull request as soon as you have a proof-of-concept ready. Don't worry if your code isn't 100% ready yet, that's ok. Be sure to add a caveat such as this one to your pull request, however:

**NOTE**: Until this notice is removed, this pull request should not be
merged.  This is an incomplete branch.

Of course, remove this once your pull request is ready, and be sure to comment letting everyone know you've done so.

Having an early pull request provides us with a way to follow the progression of your feature and make comments throughout its life. It's a lot easier to understand the changes you're making if they're smaller, so start with a prototype and be ready to iterate.

This might seem like extra work, but even we do it. Check out the network graph, all of the core contributors follow this same pattern for getting features into the project. This process ensures that the Armstrong has the best code.

Unit Tests

Please include unit tests, or be prepared to write them. We use Djangos built-in testing framework and a virtualenv wrapper to ensure that an app (in the Django sense) can be tested without having to be installed inside a full-blown project. Look at the existing projects to see how they handle tests to understand how this works.