Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added contribution guidelines & some brief testing docs.

  • Loading branch information...
commit b8103d39f20938c80afb2d3bbf2be5d8305f6419 1 parent dae4957
Daniel Lindsley toastdriven authored
Showing with 156 additions and 0 deletions.
  1. +131 −0 docs/contributing.rst
  2. +24 −0 docs/index.rst
  3. +1 −0  docs/toc.rst
131 docs/contributing.rst
View
@@ -0,0 +1,131 @@
+============
+Contributing
+============
+
+Tastypie is open-source and, as such, grows (or shrinks) & improves in part
+due to the community. Below are some guidelines on how to help with the project.
+
+
+Philosophy
+==========
+
+* Tastypie is BSD-licensed. All contributed code must be either
+
+ * the original work of the author, contributed under the BSD, or...
+ * work taken from another project released under a BSD-compatible license.
+
+* GPL'd (or similar) works are not eligible for inclusion.
+* Tastypie's git master branch should always be stable, production-ready &
+ passing all tests.
+* Major releases (1.x.x) are commitments to backward-compatibility of the public APIs.
+ Any documented API should ideally not change between major releases.
+ The exclusion to this rule is in the event of either a security issue
+ or to accommodate changes in Django itself.
+* Minor releases (x.3.x) are for the addition of substantial features or major
+ bugfixes.
+* Patch releases (x.x.4) are for minor features or bugfixes.
+
+
+Guidelines For Reporting An Issue/Feature
+=========================================
+
+So you've found a bug or have a great idea for a feature. Here's the steps you
+should take to help get it added/fixed in Tastypie:
+
+* First, check to see if there's an existing issue/pull request for the
+ bug/feature. All issues are at https://github.com/toastdriven/django-tastypie/issues
+ and pull reqs are at https://github.com/toastdriven/django-tastypie/pulls.
+* If there isn't one there, please file an issue. The ideal report includes:
+
+ * A description of the problem/suggestion.
+ * How to recreate the bug.
+ * If relevant, including the versions of your:
+
+ * Python interpreter
+ * Django
+ * Tastypie
+ * Optionally of the other dependencies involved
+
+ * Ideally, creating a pull request with a (failing) test case demonstrating
+ what's wrong. This makes it easy for us to reproduce & fix the problem.
+ Instructions for running the tests are at :doc:`index`
+
+You might also hop into the IRC channel (``#tastypie`` on ``irc.freenode.net``)
+& raise your question there, as there may be someone who can help you with a
+work-around.
+
+
+Guidelines For Contributing Code
+================================
+
+If you're ready to take the plunge & contribute back some code/docs, the
+process should look like:
+
+* Fork the project on GitHub into your own account.
+* Clone your copy of Tastypie.
+* Make a new branch in git & commit your changes there.
+* Push your new branch up to GitHub.
+* Again, ensure there isn't already an issue or pull request out there on it.
+ If there is & you feel you have a better fix, please take note of the issue
+ number & mention it in your pull request.
+* Create a new pull request (based on your branch), including what the
+ problem/feature is, versions of your software & referencing any related
+ issues/pull requests.
+
+In order to be merged into Tastypie, contributions must have the following:
+
+* A solid patch that:
+
+ * is clear.
+ * works across all supported versions of Python/Django.
+ * follows the existing style of the code base (mostly PEP-8).
+ * comments included as needed.
+
+* A test case that demonstrates the previous flaw that now passes
+ with the included patch.
+* If it adds/changes a public API, it must also include documentation
+ for those changes.
+* Must be appropriately licensed (see "Philosophy").
+* Adds yourself to the AUTHORS file.
+
+If your contribution lacks any of these things, they will have to be added
+by a core contributor before being merged into Tastypie proper, which may take
+substantial time for the all-volunteer team to get to.
+
+
+Guidelines For Core Contributors
+================================
+
+If you've been granted the commit bit, here's how to shepherd the changes in:
+
+* Any time you go to work on Tastypie, please use ``git pull --rebase`` to fetch
+ the latest changes.
+* Any new features/bug fixes must meet the above guidelines for contributing
+ code (solid patch/tests passing/docs included).
+* Commits are typically cherry-picked onto a branch off master.
+
+ * This is done so as not to include extraneous commits, as some people submit
+ pull reqs based on their git master that has other things applied to it.
+
+* A set of commits should be squashed down to a single commit.
+
+ * ``git merge --squash`` is a good tool for performing this, as is
+ ``git rebase -i HEAD~N``.
+ * This is done to prevent anyone using the git repo from accidently pulling
+ work-in-progress commits.
+
+* Commit messages should use past tense, describe what changed & thank anyone
+ involved. Examples::
+
+ """Added a new way to do per-object authorization."""
+ """Fixed a bug in ``Serializer.to_xml``. Thanks to joeschmoe for the report!"""
+ """BACKWARD-INCOMPATIBLE: Altered the arguments passed to ``Bundle.__init__.
+
+ Further description appears here if the change warrants an explanation
+ as to why it was done."""
+
+* For any patches applied from a contributor, please ensure their name appears
+ in the AUTHORS file.
+* When closing issues or pull requests, please reference the SHA in the closing
+ message (i.e. ``Thanks! Fixed in SHA: 6b93f6``). GitHub will automatically
+ link to it.
24 docs/index.rst
View
@@ -28,6 +28,7 @@ interfaces.
cookbook
debugging
who_uses
+ contributing
Getting Help
@@ -101,3 +102,26 @@ Optional
* biplist (http://explorapp.com/biplist/) if using the binary plist serializer
.. _Pip: http://pip.openplans.org/
+
+
+Running The Tests
+=================
+
+The easiest way to get setup to run Tastypie's tests looks like::
+
+ $ git clone https://github.com/toastdriven/django-tastypie.git
+ $ cd django-tastypie
+ $ virtualenv env
+ $ . env/bin/activate
+ $ ./env/bin/pip install -U -r requirements.txt
+
+Then running the tests is as simple as::
+
+ # From the same directory as above:
+ $ cd tests
+ $ ./run_all_test.sh
+
+Tastypie is maintained with all tests passing at all times. If you find a
+failure, please `report it`_ along with the versions of the installed software.
+
+.. _`report it`: https://github.com/toastdriven/django-tastypie/issues
1  docs/toc.rst
View
@@ -25,6 +25,7 @@ Table Of Contents
cookbook
debugging
who_uses
+ contributing
Indices and tables
Please sign in to comment.
Something went wrong with that request. Please try again.