5
5
:Author: David Goodger; open to all Docutils developers
6
6
:Contact: goodger@python.org
7
:Date: $Date: 2004/07/27 22:30:23 $
8
:Revision: $Revision: 1.8 $
7
:Date: $Date: 2005-04-07 18:22:05 +0200 (Thu, 07 Apr 2005) $
8
:Revision: $Revision: 3183 $
9
9
:Copyright: This document has been placed in the public domain.
13
A few quotes sum up the policies of the Docutils project. The IETF's
14
classic credo (by MIT professor Dave Clark) is an ideal we can aspire
13
Docutils is a meritocracy based on code contribution and lots of
14
discussion [#bcs]_. A few quotes sum up the policies of the Docutils
15
project. The IETF's classic credo (by MIT professor Dave Clark) is an
16
ideal we can aspire to:
17
18
We reject: kings, presidents, and voting. We believe in: rough
18
19
consensus and running code.
35
36
possible. The policies below should not be thought of as barriers,
36
37
but merely as a codification of experience to date. These are "best
37
38
practices", not absolutes; exceptions are expected, tolerated, and
38
used as a source of improvement.
39
used as a source of improvement. Feedback and criticism is welcome.
40
41
As for control issues, Emmett Plant (CEO of the Xiph.org Foundation,
41
42
originators of Ogg Vorbis) put it well when he said:
43
44
Open source dictates that you lose a certain amount of control
44
45
over your codebase, and that's okay with us.
47
.. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion
48
project <http://www.red-bean.com/sussman/svn-anti-fud.html>`__.
47
51
Python Coding Conventions
48
52
=========================
57
61
The Docutils project shall follow the generic coding conventions as
58
62
specified in the `Style Guide for Python Code`_ and `Docstring
59
Conventions`_ PEPs, with the following clarifications (from most to
63
Conventions`_ PEPs, with the following clarifications and extensions:
62
65
* 4 spaces per indentation level. No tabs.
81
84
"note_explicit_target", "explicit_target"). If in doubt, use
87
* Avoid functional constructs (lambda, filter, map, etc.). Use list
88
comprehensions instead.
90
* Avoid ``from __future__ import`` constructs; we don't want them in
84
93
* Use 'single quotes' for string literals, and """triple double
85
94
quotes""" for docstrings.
96
105
The majority of the Docutils project code and documentation has been
97
106
placed in the public domain. Unless clearly and explicitly indicated
98
107
otherwise, any patches (modifications to existing files) submitted to
99
the project for inclusion (via CVS, SourceForge trackers, mailing
100
lists, or private email) are assumed to be in the public domain as
108
the project for inclusion (via Subversion, SourceForge trackers,
109
mailing lists, or private email) are assumed to be in the public
103
112
Any new files contributed to the project should clearly state their
104
113
intentions regarding copyright, in one of the following ways:
126
Instructions for CVS access can be found at
127
http://sourceforge.net/cvs/?group_id=38414. Anyone can access the CVS
135
Please see the `repository documentation`_ for details on how to
136
access Docutils' Subversion repository. Anyone can access the
128
137
repository anonymously. Only project developers can make changes.
129
See `Setting Up For Docutils Development`_ below for more info.
138
Also see `Setting Up For Docutils Development`_ below for more info.
140
.. _repository documentation: repository.html
131
142
Unless you really *really* know what you're doing, please limit your
132
CVS commands to ``cvs checkout``, ``cvs commit/checkin``, and ``cvs
133
add``. Do **NOT** use ``cvs import`` unless you're absolutely sure
143
Subversion commands to ``svn checkout``, ``svn commit``, and ``svn
144
add``. Do **NOT** use ``svn import`` unless you're absolutely sure
134
145
you know what you're doing. Even then, grab a copy of the `nightly
135
CVS tarball`_, set it up on your own machine, and experiment *there*
146
repository tarball`_, set it up on your own machine, and experiment
147
*there* first (but remove hooks/post-commit first).
138
The `main source tree`_ ("docutils" CVS module) should always be kept
139
in a stable state (usable and as problem-free as possible). The
149
The `main source tree`_ ("trunk/docutils" directory) should always be
150
kept in a stable state (usable and as problem-free as possible). The
140
151
Docutils project shall follow the `Python Check-in Policies`_ (as
141
152
applicable), with particular emphasis as follows:
149
Docutils currently supports Python 2.1 [1]_ or later, with some
150
things only working (and being tested) on 2.3. Therefore, you
151
should actually have Pythons 2.1 [1]_, 2.2 and 2.3 installed and
152
always run the tests on all of them. (A good way to do that is to
153
always run the test suite through a short script that runs
160
Docutils currently supports Python 2.1 [#py21]_ or later, with some
161
things only working (and being tested) on Python 2.3+. Therefore,
162
you should actually have Pythons 2.1 [#py21]_, 2.2 and 2.3 installed
163
and always run the tests on all of them. (A good way to do that is
164
to always run the test suite through a short script that runs
154
165
``alltests.py`` under each version of Python.) If you can't afford
155
166
intalling 3 Python versions, the edge cases (2.1 and 2.3) should
156
167
cover most of it.
158
.. [1] Python 2.1 may be used providing the compiler package is
169
.. [#py21] Python 2.1 may be used providing the compiler package is
159
170
installed. The compiler package can be found in the Tools/
160
171
directory of Python 2.1's source distribution.
167
178
* `PEP 290 - Code Migration and Modernization`__
169
180
__ http://www.python.org/doc/2.2.3/whatsnew/whatsnew22.html
170
__ http://www.python.org/doc/2.3.4/whatsnew/whatsnew23.html
171
__ http://www.python.org/dev/doc/devel/whatsnew/whatsnew24.html
181
__ http://www.python.org/doc/2.3.5/whatsnew/whatsnew23.html
182
__ http://www.python.org/doc/2.4.1/whatsnew/whatsnew24.html
172
183
__ http://www.python.org/peps/pep-0290.html
174
Note that there are currently some known issues with development
175
versions of Python 2.4-to-be (see the thread about `Python 2.4
176
compatibility`_ for details). There is no need to pass the test
177
suite under it, unless you wish to tackle these issues...
179
.. _Python 2.4 compatibility:
180
http://thread.gmane.org/gmane.text.docutils.devel/2071
182
185
* When adding new functionality (or fixing bugs), be sure to add test
183
186
cases to the test suite. Practise test-first programming; it's fun,
184
187
it's addictive, and it works!
186
* The `sandbox CVS directory`_ is the place to put new, incomplete or
189
* The `sandbox directory`_ is the place to put new, incomplete or
187
190
experimental code. See `Additions to Docutils`_ and `The Sandbox`_
198
201
possible, and deal with any aberrations if (and hopefully not when)
199
202
they happen. I'd rather see a torrent of loose contributions than
200
203
just a trickle of perfect-as-they-stand changes. The occasional
201
mistake is easy to fix. That's what CVS is for.
204
mistake is easy to fix. That's what Subversion is for.
203
206
.. _main source tree:
204
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/docutils/
207
http://svn.berlios.de/viewcvs/docutils/trunk/docutils/
205
208
.. _Python Check-in Policies: http://www.python.org/dev/tools.html
206
.. _sandbox CVS directory:
207
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/
208
.. _nightly CVS tarball:
209
http://cvs.sourceforge.net/cvstarballs/docutils-cvsroot.tar.bz2
209
.. _sandbox directory:
210
http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/
211
.. _nightly repository tarball:
212
http://svn.berlios.de/svndumps/docutils-repos.gz
212
215
Additions to Docutils
213
216
---------------------
215
218
Additions to the project, such as new components, should be developed
216
in the `sandbox CVS directory`_ until they're in `good shape`_,
217
usable_, documented_, and `reasonably complete`_. Adding to the `main
218
source tree`_ or to a `parallel project`_ implies a commitment to the
219
in the `sandbox directory`_ until they're in `good shape`_, usable_,
220
documented_, and `reasonably complete`_. Adding to the `main source
221
tree`_ or to a `parallel project`_ implies a commitment to the
219
222
Docutils user community.
221
224
* Why the sandbox?
257
260
.. _Docutils Configuration Files: ../user/config.html
263
In your ~/.cvsrc file, make sure you have a line like this::
267
This ensures that new directories are created and empty directories
268
are pruned (removed) from your working copy. In addition, these lines
274
``cvs -q`` suppresses many non-essential messages. ``-z3`` compresses
275
data between client and server. ``diff -u`` creates "unified diffs";
276
specify ``diff -c`` if you prefer context diffs.
279
263
Setting Up For Docutils Development
280
264
-----------------------------------
289
273
up your local working copy of the code. This is the recommended
292
For the bash shell and Docutils checked out from CVS in
276
For the bash shell and Docutils checked out from Subversion in
293
277
``~/projects/docutils/``, add this to your ``~/.profile``::
295
279
PYTHONPATH=$HOME/projects/docutils/docutils
329
313
(email to Doc-SIG@python.org).
330
314
* Docutils-develop__, for implementation discussions
331
315
(email to docutils-develop@lists.sourceforge.net).
332
* Docutils-checkins__, to monitor CVS checkin messages (automatically
333
generated; normally read-only).
316
* Docutils-checkins__, to monitor Subversion check-in messages
317
(automatically generated; normally read-only).
334
318
* Docutils-users__, to monitor and help out with usage issues and bug
346
The `sandbox CVS directory`_ is a place to play around, to try out and
347
share ideas. It's a part of the CVS repository but it isn't
330
The `sandbox directory`_ is a place to play around, to try out and
331
share ideas. It's a part of the Subversion repository but it isn't
348
332
distributed as part of Docutils releases. Feel free to check in code
349
to the CVS sandbox; that way people can try it out but you won't have
350
to worry about it working 100% error-free, as is the goal of the `main
333
to the sandbox; that way people can try it out but you won't have to
334
worry about it working 100% error-free, as is the goal of the `main
351
335
source tree`_. Each developer who wants to play in the sandbox should
352
336
create either a project-specific subdirectory or personal subdirectory
353
337
(suggested name: SourceForge ID, nickname, or given name + family
401
385
plug-ins, and applications of Docutils. They use Docutils, but
402
386
Docutils does not require their presence to function.
404
An official parallel project will have its own CVS directory beside
405
(or parallel to) the main Docutils CVS directory. It can have its own
406
web page in the docutils.sourceforge.net domain, its own file releases
407
and downloadable CVS snapshots, and even a mailing list if that proves
408
useful. However, an official parallel project has implications: it is
409
expected to be maintained and continue to work with changes to the
388
An official parallel project will have its own directory beside (or
389
parallel to) the main ``docutils`` directory in the Subversion
390
repository. It can have its own web page in the
391
docutils.sourceforge.net domain, its own file releases and
392
downloadable snapshots, and even a mailing list if that proves useful.
393
However, an official parallel project has implications: it is expected
394
to be maintained and continue to work with changes to the core
412
397
A parallel project requires a project leader, who must commit to
413
398
coordinate and maintain the implementation:
added
removed
docs/dev/policies.txt
