Skip to content

Commit 27d17b7

Browse files
committed
Added a contributing doc for bonus GH integration.
1 parent 71a1f0a commit 27d17b7

File tree

1 file changed

+131
-0
lines changed

1 file changed

+131
-0
lines changed

CONTRIBUTING

+131
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
============
2+
Contributing
3+
============
4+
5+
Tastypie is open-source and, as such, grows (or shrinks) & improves in part
6+
due to the community. Below are some guidelines on how to help with the project.
7+
8+
9+
Philosophy
10+
==========
11+
12+
* Tastypie is BSD-licensed. All contributed code must be either
13+
14+
* the original work of the author, contributed under the BSD, or...
15+
* work taken from another project released under a BSD-compatible license.
16+
17+
* GPL'd (or similar) works are not eligible for inclusion.
18+
* Tastypie's git master branch should always be stable, production-ready &
19+
passing all tests.
20+
* Major releases (1.x.x) are commitments to backward-compatibility of the public APIs.
21+
Any documented API should ideally not change between major releases.
22+
The exclusion to this rule is in the event of either a security issue
23+
or to accommodate changes in Django itself.
24+
* Minor releases (x.3.x) are for the addition of substantial features or major
25+
bugfixes.
26+
* Patch releases (x.x.4) are for minor features or bugfixes.
27+
28+
29+
Guidelines For Reporting An Issue/Feature
30+
=========================================
31+
32+
So you've found a bug or have a great idea for a feature. Here's the steps you
33+
should take to help get it added/fixed in Tastypie:
34+
35+
* First, check to see if there's an existing issue/pull request for the
36+
bug/feature. All issues are at https://github.com/toastdriven/django-tastypie/issues
37+
and pull reqs are at https://github.com/toastdriven/django-tastypie/pulls.
38+
* If there isn't one there, please file an issue. The ideal report includes:
39+
40+
* A description of the problem/suggestion.
41+
* How to recreate the bug.
42+
* If relevant, including the versions of your:
43+
44+
* Python interpreter
45+
* Django
46+
* Tastypie
47+
* Optionally of the other dependencies involved
48+
49+
* Ideally, creating a pull request with a (failing) test case demonstrating
50+
what's wrong. This makes it easy for us to reproduce & fix the problem.
51+
Instructions for running the tests are at :doc:`index`
52+
53+
You might also hop into the IRC channel (``#tastypie`` on ``irc.freenode.net``)
54+
& raise your question there, as there may be someone who can help you with a
55+
work-around.
56+
57+
58+
Guidelines For Contributing Code
59+
================================
60+
61+
If you're ready to take the plunge & contribute back some code/docs, the
62+
process should look like:
63+
64+
* Fork the project on GitHub into your own account.
65+
* Clone your copy of Tastypie.
66+
* Make a new branch in git & commit your changes there.
67+
* Push your new branch up to GitHub.
68+
* Again, ensure there isn't already an issue or pull request out there on it.
69+
If there is & you feel you have a better fix, please take note of the issue
70+
number & mention it in your pull request.
71+
* Create a new pull request (based on your branch), including what the
72+
problem/feature is, versions of your software & referencing any related
73+
issues/pull requests.
74+
75+
In order to be merged into Tastypie, contributions must have the following:
76+
77+
* A solid patch that:
78+
79+
* is clear.
80+
* works across all supported versions of Python/Django.
81+
* follows the existing style of the code base (mostly PEP-8).
82+
* comments included as needed.
83+
84+
* A test case that demonstrates the previous flaw that now passes
85+
with the included patch.
86+
* If it adds/changes a public API, it must also include documentation
87+
for those changes.
88+
* Must be appropriately licensed (see "Philosophy").
89+
* Adds yourself to the AUTHORS file.
90+
91+
If your contribution lacks any of these things, they will have to be added
92+
by a core contributor before being merged into Tastypie proper, which may take
93+
substantial time for the all-volunteer team to get to.
94+
95+
96+
Guidelines For Core Contributors
97+
================================
98+
99+
If you've been granted the commit bit, here's how to shepherd the changes in:
100+
101+
* Any time you go to work on Tastypie, please use ``git pull --rebase`` to fetch
102+
the latest changes.
103+
* Any new features/bug fixes must meet the above guidelines for contributing
104+
code (solid patch/tests passing/docs included).
105+
* Commits are typically cherry-picked onto a branch off master.
106+
107+
* This is done so as not to include extraneous commits, as some people submit
108+
pull reqs based on their git master that has other things applied to it.
109+
110+
* A set of commits should be squashed down to a single commit.
111+
112+
* ``git merge --squash`` is a good tool for performing this, as is
113+
``git rebase -i HEAD~N``.
114+
* This is done to prevent anyone using the git repo from accidently pulling
115+
work-in-progress commits.
116+
117+
* Commit messages should use past tense, describe what changed & thank anyone
118+
involved. Examples::
119+
120+
"""Added a new way to do per-object authorization."""
121+
"""Fixed a bug in ``Serializer.to_xml``. Thanks to joeschmoe for the report!"""
122+
"""BACKWARD-INCOMPATIBLE: Altered the arguments passed to ``Bundle.__init__``.
123+
124+
Further description appears here if the change warrants an explanation
125+
as to why it was done."""
126+
127+
* For any patches applied from a contributor, please ensure their name appears
128+
in the AUTHORS file.
129+
* When closing issues or pull requests, please reference the SHA in the closing
130+
message (i.e. ``Thanks! Fixed in SHA: 6b93f6``). GitHub will automatically
131+
link to it.

0 commit comments

Comments
 (0)