Permalink
Fetching contributors…
Cannot retrieve contributors at this time
119 lines (85 sloc) 4.35 KB

Contributing

django-planet 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

  • django-planet 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.
  • django-planet's git master branch should always be stable, production-ready & passing all tests.

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/matagus/django-planet/issues and pull reqs are at https://github.com/matagus/django-planet/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
      • django-planet
      • 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`

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 django-planet.
  • 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 django-planet, 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 django-planet 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 djano-planet, 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.

    """Added template tag to get all posts.

    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.