First pass on contribution guide

docs/index.md

@@ -177,6 +177,7 @@ General guides to using REST framework.
 * [Browser enhancements][browser-enhancements]
 * [The Browsable API][browsableapi]
 * [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas]
+* [Contributing to REST framework][contributing]
 * [2.0 Announcement][rest-framework-2-announcement]
 * [2.2 Announcement][2.2-announcement]
 * [2.3 Announcement][2.3-announcement]

docs/template.html

@@ -102,6 +102,7 @@
                   <li><a href="{{ base_url }}/topics/browser-enhancements{{ suffix }}">Browser enhancements</a></li>
                   <li><a href="{{ base_url }}/topics/browsable-api{{ suffix }}">The Browsable API</a></li>
                   <li><a href="{{ base_url }}/topics/rest-hypermedia-hateoas{{ suffix }}">REST, Hypermedia & HATEOAS</a></li>
+                  <li><a href="{{ base_url }}/topics/contributing{{ suffix }}">Contributing to REST framework</a></li>
                   <li><a href="{{ base_url }}/topics/rest-framework-2-announcement{{ suffix }}">2.0 Announcement</a></li>
                   <li><a href="{{ base_url }}/topics/2.2-announcement{{ suffix }}">2.2 Announcement</a></li>
                   <li><a href="{{ base_url }}/topics/2.3-announcement{{ suffix }}">2.3 Announcement</a></li>

docs/topics/contributing.md

@@ -6,19 +6,27 @@
 
 There are many ways you can contribute to Django REST framework.  We'd like it to be a community-led project, so please get involved and help shape the future of the project.
 
-# Community
+## Community
 
-If you use and enjoy REST framework please consider [staring the project on GitHub][github], and [upvoting it on Django packages][django-packages].  Doing so helps potential new users see that the project is well used, and help us continue to attract new users.
+The most important thing you can do to help push the REST framework project forward is to be actively involved wherever possible.  Code contributions are often overvalued as being the primary way to get involved in a project, we don't believe that needs to be the case.
 
-You might also consider writing a blog post on your experience with using REST framework, writing a tutorial about using the project with a particular javascript framework, or simply sharing the love on Twitter.
+If you use REST framework, we'd love you to be vocal about your experiances with it - you might consider writing a blog post on your experience with using REST framework, or publishing a tutorial about using the project with a particular javascript framework.  Experiances from beginners can be particularly helpful because you'll be in the best position to assess which bits of REST framework are and aren't easy to understand and work with.
 
 Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag.
 
 When answering questions make sure to help future contributors find their way around by hyperlinking wherever possible to related threads and tickets, and include backlinks from those items if relevant. 
 
+## Code of conduct
+
+Please keep the tone polite & professional.  For some users a discussion on the REST framework mailing list or ticket tracker may be their first engagement with the open source community.  First impressions count, so let's try to make everyone feel welcome.
+
+Be mindful in the language you choose.  As an example, in an environment that is heavily male-dominated, posts that start 'Hey guys,' can come across as unintentionally exclusive.  It's just as easy, and more inclusive to use gender neutral language in those situations.
+
+The [Django code of conduct][code-of-conduct] gives a fuller set of guidelines for participating in community forums.
+
 # Issues
 
-It's really helpful if you make sure you address issues to the correct channel.  Usage questions should be directed to the [discussion group][google-group].  Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues].
+It's really helpful if you can make sure to address issues on the correct channel.  Usage questions should be directed to the [discussion group][google-group].  Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues].
 
 Some tips on good issue reporting:
 
@@ -26,30 +34,61 @@ Some tips on good issue reporting:
 * Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue.
 * If reporting a bug, then try to include a pull request with a failing test case.  This will help us quickly identify if there is a valid issue, and make sure that it gets fixed more quickly if there is one.
 
+## Triaging issues
 
+Getting involved in triaging incoming issues is a good way to start contributing.  Every single ticket that comes into the ticket tracker needs to be reviewed in order to determine what the next steps should be.  Anyone can help out with this, you just need to be willing to 
 
-* TODO: Triage
+* Read through the ticket - does it make sense, is it missing any context that would help explain it better?
+* Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group?
+* If the ticket is a bug report, can you reproduce it? Are you able to write a failing test case that demonstrates the issue and that can be submitted as a pull request?
+* If the ticket is a feature request, do you agree with it, and could the feature request instead be implemented as a third party package?
 
 # Development
 
+To start developing on Django REST framework, clone the repo:
 
-* git clone & PYTHONPATH
+    git clone git@github.com:tomchristie/django-rest-framework.git
-* Pep8
-* Recommend editor that runs pep8
 
-### Pull requests
+Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recommend you setup your editor to automatically indicated non-conforming styles.
 
-* Make pull requests early
+## Testing
-* Describe branching
 
-### Managing compatibility issues
+To run the tests, clone the repository, and then:
 
-* Describe compat module
+    # Setup the virtual environment
+    virtualenv env
+    env/bin/activate
+    pip install -r requirements.txt
+    pip install -r optionals.txt
 
-# Testing
+    # Run the tests
+    rest_framework/runtests/runtests.py
 
-* Running the tests
+You can also use the excellent `[tox][tox]` testing tool to run the tests against all supported versions of Python and Django.  Install `tox` globally, and then simply run:
-* tox
+
+    tox
+
+## Pull requests
+
+It's a good idea to make pull requests early on.  A pull request represents the start of a discussion, and doesn't necessarily need to be the final, finished submission.
+
+It's also always best to make a new branch before starting work on a pull request.  This means that you'll be able to later switch back to working on another seperate issue without interfering with an ongoing pull requests.
+
+It's also useful to remember that if you have an outstanding pull request then pushing new commits to your GitHub repo will also automatically update the pull requests.
+
+GitHub's documentation for working on pull requests is [available here][pull-requests].
+
+Always run the tests before submitting pull requests, and ideally run `tox` in order to check that your modifications are compatible with both Python 2 and Python 3, and that they run properly on all supported versions of Django.
+
+Once you've made a pull request take a look at the travis build status in the GitHub interface and make sure the tests are runnning as you'd expect.
+
+![Travis status][travis-status]
+
+*Above: Travis build notifications*
+
+## Managing compatibility issues
+
+Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment.  Any code that branches in this way should be isolated into the `compat.py` module, and should provide a single common interface that the rest of the codebase can use.
 
 # Documentation
 
@@ -77,7 +116,7 @@ Some other tips:
 
 * Keep paragraphs reasonably short.
 * Use double spacing after the end of sentences.
-* Don't use the abbreviations such as 'e.g..' but instead use long form, such as 'For example'.
+* Don't use the abbreviations such as 'e.g.' but instead use long form, such as 'For example'.
 
 ## Markdown style
 
@@ -118,25 +157,19 @@ If you want to draw attention to a note or warning, use a pair of enclosing line
 
     ---
     
-    **Note:** Make sure you do this thing.
+    **Note:** A useful documentation note.
     
     ---
 
-# Third party packages
-
-* Django reusable app
-
-# Core committers
-
-* Still use pull reqs
-* Credits
-
 [cite]: http://www.w3.org/People/Berners-Lee/FAQ.html
-[github]: https://github.com/tomchristie/django-rest-framework
+[code-of-conduct]: https://www.djangoproject.com/conduct/
-[django-packages]: https://www.djangopackages.com/grids/g/api/
 [google-group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
 [so-filter]: http://stackexchange.com/filters/66475/rest-framework
 [issues]: https://github.com/tomchristie/django-rest-framework/issues?state=open
+[pep-8]: http://www.python.org/dev/peps/pep-0008/
+[travis-status]: ../img/travis-status.png
+[pull-requests]: https://help.github.com/articles/using-pull-requests
+[tox]: http://tox.readthedocs.org/en/latest/
 [markdown]: http://daringfireball.net/projects/markdown/basics
 [docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs
 [mou]: http://mouapp.com/