Skip to content
Newer
Older
100644 192 lines (135 sloc) 6.64 KB
a3139e6 @digi604 contribution.rst to root for github
digi604 authored
1 ##########################
2 Contributing to django CMS
3 ##########################
4
5 Like every open-source project, django CMS is always looking for motivated
5727181 @evildmp #1535 docs on contribution and testing
evildmp authored
6 individuals to contribute to its source code. However, to ensure the highest
7 code quality and keep the repository nice and tidy, everybody has to follow a
8 few rules (nothing major, I promise :) )
9
10
11 .. ATTENTION::
12
13 If you think you have discovered a security issue in our code, please report
14 it **privately**, by emailing us at `security@django-cms.org`_.
15
16 Please don't raise it on:
17
18 * IRC
19 * GitHub
20 * either of our email lists
21
22 or in any other public forum until we have had a chance to deal with it.
a3139e6 @digi604 contribution.rst to root for github
digi604 authored
23
24
25 *********
26 Community
27 *********
28
29 People interested in developing for the django CMS should join the
30 `django-cms-developers`_ mailing list as well as heading over to #django-cms on
31 the `freenode`_ IRC network for help and to discuss the development.
32
33 You may also be interested in following `@djangocmsstatus`_ on twitter to get the
34 GitHub commits as well as the hudson build reports. There is also a `@djangocms`_
35 account for less technical announcements.
36
37
38 *************
39 In a nutshell
40 *************
41
42 Here's what the contribution process looks like, in a bullet-points fashion, and
43 only for the stuff we host on GitHub:
44
45 #. django CMS is hosted on `GitHub`_, at https://github.com/divio/django-cms
46 #. The best method to contribute back is to create an account there, then fork
47 the project. You can use this fork as if it was your own project, and should
48 push your changes to it.
49 #. When you feel your code is good enough for inclusion, "send us a `pull
50 request`_", by using the nice GitHub web interface.
51
52
53
54 *****************
55 Contributing Code
56 *****************
57
58
59 Getting the source code
60 =======================
61
62 If you're interested in developing a new feature for the CMS, it is recommended
63 that you first discuss it on the `django-cms-developers`_ mailing list so as
64 not to do any work that will not get merged in anyway.
65
66 - Code will be reviewed and tested by at least one core developer, preferably
67 by several. Other community members are welcome to give feedback.
68 - Code *must* be tested. Your pull request should include unit-tests (that cover
69 the piece of code you're submitting, obviously)
70 - Documentation should reflect your changes if relevant. There is nothing worse
71 than invalid documentation.
72 - Usually, if unit tests are written, pass, and your change is relevant, then
73 it'll be merged.
74
75 Since we're hosted on GitHub, django CMS uses `git`_ as a version control system.
76
77 The `GitHub help`_ is very well written and will get you started on using git
78 and GitHub in a jiffy. It is an invaluable resource for newbies and old timers
79 alike.
80
81
82 Syntax and conventions
83 ======================
84
85 We try to conform to `PEP8`_ as much as possible. A few highlights:
86
87 - Indentation should be exactly 4 spaces. Not 2, not 6, not 8. **4**. Also, tabs
88 are evil.
89 - We try (loosely) to keep the line length at 79 characters. Generally the rule
90 is "it should look good in a terminal-base editor" (eg vim), but we try not be
91 [Godwin's law] about it.
92
93
94 Process
95 =======
96
97 This is how you fix a bug or add a feature:
98
99 #. `fork`_ us on GitHub.
100 #. Checkout your fork.
5727181 @evildmp #1535 docs on contribution and testing
evildmp authored
101 #. *Hack hack hack*, *test test test*, *commit commit commit*, test again.
a3139e6 @digi604 contribution.rst to root for github
digi604 authored
102 #. Push to your fork.
103 #. Open a pull request.
104
5727181 @evildmp #1535 docs on contribution and testing
evildmp authored
105 And at any point in that process, you can add: *discuss discuss discuss*,
106 because it's always useful for everyone to pass ideas around and look at thngs
107 together.
a3139e6 @digi604 contribution.rst to root for github
digi604 authored
108
5727181 @evildmp #1535 docs on contribution and testing
evildmp authored
109 We have an IRC channel, our `django-cms-developers`_ email list,
110 and of course the code reviews mechanism on GitHub - do use them.
a3139e6 @digi604 contribution.rst to root for github
digi604 authored
111
112
113 **************************
114 Contributing Documentation
115 **************************
116
117 Perhaps considered "boring" by hard-core coders, documentation is sometimes even
118 more important than code! This is what brings fresh blood to a project, and
119 serves as a reference for old timers. On top of this, documentation is the one
120 area where less technical people can help most - you just need to write
121 semi-decent English. People need to understand you. We don't care about style or
122 correctness.
123
124 Documentation should be:
125
126 - We use `Sphinx`_/`restructuredText`_. So obviously this is the format you should
127 use :) File extensions should be .rst.
128 - Written in English. We could discuss how it would bring more people to the
129 project by having a Klingon or some other translation, but that's a problem we
130 will confront once we already have good documentation in English.
131 - Accessible. You should assume the reader to be moderately familiar with
132 Python and Django, but not anything else. Link to documentation of libraries
133 you use, for example, even if they are "obvious" to you (South is the first
134 example that comes to mind - it's obvious to any Django programmer, but not to
135 any newbie at all).
136 A brief description of what it does is also welcome.
137
138 Pulling of documentation is pretty fast and painless. Usually somebody goes over
139 your text and merges it, since there are no "breaks" and that GitHub parses rst
140 files automagically it's really convenient to work with.
141
142 Also, contributing to the documentation will earn you great respect from the
143 core developers. You get good karma just like a test contributor, but you get
144 double cookie points. Seriously. You rock.
145
146 Section style
147 =============
148
149 We use Python documentation conventions for section marking:
150
151 * ``#`` with overline, for parts
152 * ``*`` with overline, for chapters
153 * ``=``, for sections
154 * ``-``, for subsections
155 * ``^``, for subsubsections
156 * ``"``, for paragraphs
157
158
159 ************
160 Translations
161 ************
162
163
164 For translators we have a `Transifex account
8e8fd35 @digi604 inserted transifex graphs
digi604 authored
165 <https://www.transifex.com/projects/p/django-cms/>`_ where you can translate
a3139e6 @digi604 contribution.rst to root for github
digi604 authored
166 the .po files and don't need to install git or mercurial to be able to
167 contribute. All changes there will be automatically sent to the project.
168
dc7937c @digi604 fixes sphinx warning
digi604 authored
169
170 .. raw:: html
171
172 Top translations django-cms core:<br/>
173
174 <img border="0" src="https://www.transifex.com/projects/p/django-cms/resource/core/chart/image_png"/>
175
176
8e8fd35 @digi604 inserted transifex graphs
digi604 authored
177
5727181 @evildmp #1535 docs on contribution and testing
evildmp authored
178 .. _security@django-cms.org: mailto:security@django-cms.org
a3139e6 @digi604 contribution.rst to root for github
digi604 authored
179 .. _fork: http://github.com/divio/django-cms
180 .. _Sphinx: http://sphinx.pocoo.org/
181 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
182 .. _django-cms-developers: http://groups.google.com/group/django-cms-developers
183 .. _GitHub : http://www.github.com
184 .. _GitHub help : http://help.github.com
185 .. _freenode : http://freenode.net/
186 .. _@djangocmsstatus : https://twitter.com/djangocmsstatus
187 .. _@djangocms : https://twitter.com/djangocms
188 .. _pull request : http://help.github.com/send-pull-requests/
189 .. _git : http://git-scm.com/
190 .. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
191
Something went wrong with that request. Please try again.