1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
Contributing
============
Like every open-source project, Django Compressor is always looking for
motivated individuals to contribute to it's source code.
However, to ensure the highest code quality and keep the repository nice and
tidy, everybody has to follow a few rules (nothing major, I promise :) )
Community
---------
People interested in developing for the Django Compressor should:
#. Head over to #django-compressor on the `freenode`_ IRC network for help and to
discuss the development.
#. Open an issue on GitHub explaining your ideas.
In a nutshell
-------------
Here's what the contribution process looks like, in a bullet-points fashion,
and only for the stuff we host on github:
#. Django Compressor is hosted on `github`_, at https://github.com/django-compressor/django-compressor
#. The best method to contribute back is to create a github account, then fork
the project. You can use this fork as if it was your own project, and should
push your changes to it.
#. When you feel your code is good enough for inclusion, "send us a `pull
request`_", by using the nice github web interface.
Contributing Code
-----------------
Getting the source code
^^^^^^^^^^^^^^^^^^^^^^^
If you're interested in developing a new feature for Compressor, it is
recommended that you first discuss it on IRC not to do any work that will
not get merged in anyway.
- Code will be reviewed and tested by at least one core developer, preferably
by several. Other community members are welcome to give feedback.
- Code *must* be tested. Your pull request should include unit-tests (that
cover the piece of code you're submitting, obviously)
- Documentation should reflect your changes if relevant. There is nothing
worse than invalid documentation.
- Usually, if unit tests are written, pass, and your change is relevant, then
it'll be merged.
Since it's hosted on github, Django Compressor uses `git`_ as a version
control system.
The `github help`_ is very well written and will get you started on using git
and github in a jiffy. It is an invaluable resource for newbies and old timers
alike.
Syntax and conventions
^^^^^^^^^^^^^^^^^^^^^^
We try to conform to `PEP8`_ as much as possible. A few highlights:
- Indentation should be exactly 4 spaces. Not 2, not 6, not 8. **4**. Also,
tabs are evil.
- We try (loosely) to keep the line length at 79 characters. Generally the
rule is "it should look good in a terminal-base editor" (eg vim), but we
try not be [Godwin's law] about it.
Process
^^^^^^^
This is how you fix a bug or add a feature:
#. `Fork`_ us on github.
#. Checkout your fork.
#. Hack hack hack, test test test, commit commit commit, test again.
#. Push to your fork.
#. Open a pull request.
Tests
^^^^^
Having a wide and comprehensive library of unit-tests and integration tests is
of exceeding importance. Contributing tests is widely regarded as a very
prestigious contribution (you're making everybody's future work much easier by
doing so). Good karma for you. Cookie points. Maybe even a beer if we meet in
person :)
Generally tests should be:
- Unitary (as much as possible). I.E. should test as much as possible only one
function/method/class. That's the very definition of unit tests.
- Integration tests are interesting too obviously, but require more time to
maintain since they have a higher probability of breaking.
- Short running. No hard numbers here, but if your one test doubles the time
it takes for everybody to run them, it's probably an indication that you're
doing it wrong.
In a similar way to code, pull requests will be reviewed before pulling
(obviously), and we encourage discussion via code review (everybody learns
something this way) or IRC discussions.
Running the tests
^^^^^^^^^^^^^^^^^
To run the tests simply fork django_compressor, make the changes and open
a pull request. The Travis_ bot will automatically run the tests of your
branch/fork (see the `pull request announcment`_ for more info) and add a
comment about the test results to the pull requests. Alternatively you
can also login at Travis and enable your fork to run there, too. See the
`Travis documentation`_ to read about how to do that.
Alternatively, create a virtualenv and activate it, then install the
requirements **in the virtualenv**::
$ virtualenv compressor_test
$ source compressor_test/bin/activate
(compressor_test) $ make testenv
Then run ``make test`` to run the tests. Please note that this only tests
django_compressor in the Python version you've created the virtualenv with
not all the versions that are required to be supported.
Contributing Documentation
--------------------------
Perhaps considered "boring" by hard-core coders, documentation is sometimes
even more important than code! This is what brings fresh blood to a project,
and serves as a reference for old timers. On top of this, documentation is
the one area where less technical people can help most - you just need to
write a semi-decent English. People need to understand you.
Documentation should be:
- We use `Sphinx`_/`restructuredText`_. So obviously this is the format you
should use :) File extensions should be ``.txt``.
- Written in English. We can discuss how it would bring more people to the
project to have a Klingon translation or anything, but that's a problem we
will ask ourselves when we already have a good documentation in English.
- Accessible. You should assume the reader to be moderately familiar with
Python and Django, but not anything else. Link to documentation of libraries
you use, for example, even if they are "obvious" to you. A brief
description of what it does is also welcome.
Pulling of documentation is pretty fast and painless. Usually somebody goes
over your text and merges it, since there are no "breaks" and that github
parses rst files automagically it's really convenient to work with.
Also, contributing to the documentation will earn you great respect from the
core developers. You get good karma just like a test contributor, but you get
double cookie points. Seriously. You rock.
.. note::
This very document is based on the contributing docs of the
`django CMS`_ project. Many thanks for allowing us to steal it!
.. _Fork: http://github.com/django-compressor/django-compressor
.. _Travis: http://travis-ci.org/
.. _`pull request announcment`: http://about.travis-ci.org/blog/announcing-pull-request-support/
.. _`Travis documentation`: http://about.travis-ci.org/docs/
.. _Sphinx: http://sphinx.pocoo.org/
.. _PEP8: http://www.python.org/dev/peps/pep-0008/
.. _github : http://www.github.com
.. _github help : http://help.github.com
.. _freenode : http://freenode.net/
.. _@jezdez : https://twitter.com/jezdez
.. _pull request : http://help.github.com/send-pull-requests/
.. _git : http://git-scm.com/
.. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
.. _`django CMS`: http://www.django-cms.org/
|
