Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 92 lines (73 sloc) 3.936 kB
68a0b87 @acdha Add a CONTRIBUTING.md file for Github
acdha authored
1 Contributing
2 ============
3
4 Haystack is open-source and, as such, grows (or shrinks) & improves in part
5 due to the community. Below are some guidelines on how to help with the project.
6
7
8 Philosophy
9 ----------
10
11 * Haystack is BSD-licensed. All contributed code must be either
12 * the original work of the author, contributed under the BSD, or...
13 * work taken from another project released under a BSD-compatible license.
14 * GPL'd (or similar) works are not eligible for inclusion.
15 * Haystack's git master branch should always be stable, production-ready &
16 passing all tests.
17 * Major releases (1.x.x) are commitments to backward-compatibility of the public APIs.
18 Any documented API should ideally not change between major releases.
19 The exclusion to this rule is in the event of either a security issue
20 or to accommodate changes in Django itself.
21 * Minor releases (x.3.x) are for the addition of substantial features or major
22 bugfixes.
23 * Patch releases (x.x.4) are for minor features or bugfixes.
24
25
26 Guidelines For Reporting An Issue/Feature
27 -----------------------------------------
28
29 So you've found a bug or have a great idea for a feature. Here's the steps you
30 should take to help get it added/fixed in Haystack:
31
32 * First, check to see if there's an existing issue/pull request for the
33 bug/feature. All issues are at https://github.com/toastdriven/django-haystack/issues
34 and pull reqs are at https://github.com/toastdriven/django-haystack/pulls.
35 * If there isn't one there, please file an issue. The ideal report includes:
36 * A description of the problem/suggestion.
37 * How to recreate the bug.
38 * If relevant, including the versions of your:
39 * Python interpreter
40 * Django
41 * Haystack
42 * Search engine used (as well as bindings)
43 * Optionally of the other dependencies involved
6df822f @acdha Docs: add Github style guide link to pull request instructions
acdha authored
44 * Ideally, creating a pull request with a (failing) test case demonstrating
45 what's wrong. This makes it easy for us to reproduce & fix the problem.
68a0b87 @acdha Add a CONTRIBUTING.md file for Github
acdha authored
46
6df822f @acdha Docs: add Github style guide link to pull request instructions
acdha authored
47 Github has a great guide for writing an effective pull request:
48 https://github.com/blog/1943-how-to-write-the-perfect-pull-request
49
50 Instructions for running the tests are at
51 http://django-haystack.readthedocs.org/en/latest/running_tests.html
68a0b87 @acdha Add a CONTRIBUTING.md file for Github
acdha authored
52
53 You might also hop into the IRC channel (`#haystack` 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 Haystack.
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 Haystack, contributions must have the following:
76
77 * A solid patch that:
78 * is clear.
79 * works across all supported versions of Python/Django.
80 * follows the existing style of the code base (mostly PEP-8).
81 * comments included as needed to explain why the code functions as it does
82 * A test case that demonstrates the previous flaw that now passes
83 with the included patch.
84 * If it adds/changes a public API, it must also include documentation
85 for those changes.
86 * Must be appropriately licensed (see [Philosophy](#philosophy)).
87 * Adds yourself to the AUTHORS file.
88
89 If your contribution lacks any of these things, they will have to be added
90 by a core contributor before being merged into Haystack proper, which may take
91 substantial time for the all-volunteer team to get to.
Something went wrong with that request. Please try again.