1
===========================
2
Docutils Project Policies
3
===========================
5
:Author: David Goodger; open to all Docutils developers
6
:Contact: goodger@python.org
7
:Date: $Date: 2005-11-14 19:11:32 +0100 (Mon, 14 Nov 2005) $
8
:Revision: $Revision: 4048 $
9
:Copyright: This document has been placed in the public domain.
13
The Docutils project group is a meritocracy based on code contribution
14
and lots of discussion [#bcs]_. A few quotes sum up the policies of
15
the Docutils project. The IETF's classic credo (by MIT professor Dave
16
Clark) is an ideal we can aspire to:
18
We reject: kings, presidents, and voting. We believe in: rough
19
consensus and running code.
21
As architect, chief cook and bottle-washer, David Goodger currently
22
functions as BDFN (Benevolent Dictator For Now). (But he would
23
happily abdicate the throne given a suitable candidate. Any takers?)
25
Eric S. Raymond, anthropologist of the hacker subculture, writes in
26
his essay `The Magic Cauldron`_:
28
The number of contributors [to] projects is strongly and inversely
29
correlated with the number of hoops each project makes a user go
30
through to contribute.
32
We will endeavour to keep the barrier to entry as low as possible.
33
The policies below should not be thought of as barriers, but merely as
34
a codification of experience to date. These are "best practices";
35
guidelines, not absolutes. Exceptions are expected, tolerated, and
36
used as a source of improvement. Feedback and criticism is welcome.
38
As for control issues, Emmett Plant (CEO of the Xiph.org Foundation,
39
originators of Ogg Vorbis) put it well when he said:
41
Open source dictates that you lose a certain amount of control
42
over your codebase, and that's okay with us.
44
.. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion
45
project <http://www.red-bean.com/sussman/svn-anti-fud.html>`__.
47
.. _The Magic Cauldron:
48
http://www.catb.org/~esr/writings/magic-cauldron/
51
Python Coding Conventions
52
=========================
54
Contributed code will not be refused merely because it does not
55
strictly adhere to these conditions; as long as it's internally
56
consistent, clean, and correct, it probably will be accepted. But
57
don't be surprised if the "offending" code gets fiddled over time to
58
conform to these conventions.
60
The Docutils project shall follow the generic coding conventions as
61
specified in the `Style Guide for Python Code`_ and `Docstring
62
Conventions`_ PEPs, summarized, clarified, and extended as follows:
64
* 4 spaces per indentation level. No hard tabs.
66
* Use only 7-bit ASCII, no 8-bit strings. See `Docutils
67
Internationalization`_.
69
* No one-liner compound statements (i.e., no ``if x: return``: use two
70
lines & indentation), except for degenerate class or method
71
definitions (i.e., ``class X: pass`` is OK.).
73
* Lines should be no more than 78 characters long.
75
* Use "StudlyCaps" for class names (except for element classes in
78
* Use "lowercase" or "lowercase_with_underscores" for function,
79
method, and variable names. For short names, maximum two words,
80
joined lowercase may be used (e.g. "tagname"). For long names with
81
three or more words, or where it's hard to parse the split between
82
two words, use lowercase_with_underscores (e.g.,
83
"note_explicit_target", "explicit_target"). If in doubt, use
86
* Avoid lambda expressions, which are inherently difficult to
87
understand. Named functions are preferable and superior: they're
88
faster (no run-time compilation), and well-chosen names serve to
89
document and aid understanding.
91
* Avoid functional constructs (filter, map, etc.). Use list
92
comprehensions instead.
94
* Avoid ``from __future__ import`` constructs. They are inappropriate
97
* Use 'single quotes' for string literals, and """triple double
98
quotes""" for docstrings.
100
.. _Style Guide for Python Code:
101
http://www.python.org/peps/pep-0008.html
102
.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html
103
.. _Docutils Internationalization: ../howto/i18n.html#python-code
106
Documentation Conventions
107
=========================
109
* Docutils documentation is written using reStructuredText, of course.
111
* Use 7-bit ASCII if at all possible, and Unicode substitutions when
114
* Use the following section title adornment styles::
120
--------------------------------------------
121
Document Subtitle, or Major Division Title
122
--------------------------------------------
136
* Use two blank lines before each section/subsection/etc. title. One
137
blank line is sufficient between immediately adjacent titles.
139
* Add a bibliographic field list immediately after the document
140
title/subtitle. See the beginning of this document for an example.
142
* Add an Emacs "local variables" block in a comment at the end of the
143
document. See the end of this document for an example.
146
Copyrights and Licensing
147
========================
149
The majority of the Docutils project code and documentation has been
150
placed in the public domain. Unless clearly and explicitly indicated
151
otherwise, any patches (modifications to existing files) submitted to
152
the project for inclusion (via Subversion, SourceForge trackers,
153
mailing lists, or private email) are assumed to be in the public
156
Any new files contributed to the project should clearly state their
157
intentions regarding copyright, in one of the following ways:
159
* Public domain (preferred): include the statement "This
160
module/document has been placed in the public domain."
162
* Copyright & open source license: include a copyright notice, along
163
with either an embedded license statement, a reference to an
164
accompanying license file, or a license URL.
166
One of the goals of the Docutils project, once complete, is to be
167
incorporated into the Python standard library. At that time copyright
168
of the Docutils code will be assumed by or transferred to the Python
169
Software Foundation (PSF), and will be released under Python's
170
license. If the copyright/license option is chosen for new files, the
171
license should be compatible with Python's current license, and the
172
author(s) of the files should be willing to assign copyright to the
173
PSF. The PSF accepts the `Academic Free License v. 2.1
174
<http://opensource.org/licenses/afl-2.1.php>`_ and the `Apache
175
License, Version 2.0 <http://opensource.org/licenses/apache2.0.php>`_.
178
Subversion Repository
179
=====================
181
Please see the `repository documentation`_ for details on how to
182
access Docutils' Subversion repository. Anyone can access the
183
repository anonymously. Only project developers can make changes.
184
(If you would like to become a project developer, just ask!) Also see
185
`Setting Up For Docutils Development`_ below for some useful info.
187
Unless you really *really* know what you're doing, please do *not* use
188
``svn import``. It's quite easy to mess up the repository with an
191
.. _repository documentation: repository.html
197
(These branch policies go into effect with Docutils 0.4.)
199
The "docutils" directory of the **trunk** (a.k.a. the **Docutils
200
core**) is used for active -- but stable, fully tested, and reviewed
203
There will be at least one active **maintenance branch** at a time,
204
based on at least the latest feature release. For example, when
205
Docutils 0.5 is released, its maintenance branch will take over, and
206
the 0.4.x maintenance branch may be retired. Maintenance branches
207
will receive bug fixes only; no new features will be allowed here.
209
Obvious and uncontroversial bug fixes *with tests* can be checked in
210
directly to the core and to the maintenance branches. Don't forget to
211
add test cases! Many (but not all) bug fixes will be applicable both
212
to the core and to the maintenance branches; these should be applied
213
to both. No patches or dedicated branches are required for bug fixes,
214
but they may be used. It is up to the discretion of project
215
developers to decide which mechanism to use for each case.
217
Feature additions and API changes will be done in **feature
218
branches**. Feature branches will not be managed in any way.
219
Frequent small checkins are encouraged here. Feature branches must be
220
discussed on the docutils-develop mailing list and reviewed before
221
being merged into the core.
227
Before a new feature, an API change, or a complex, disruptive, or
228
controversial bug fix can be checked in to the core or into a
229
maintenance branch, it must undergo review. These are the criteria:
231
* The branch must be complete, and include full documentation and
234
* There should ideally be one branch merge commit per feature or
235
change. In other words, each branch merge should represent a
238
* The code must be stable and uncontroversial. Moving targets and
239
features under debate are not ready to be merged.
241
* The code must work. The test suite must complete with no failures.
242
See `Docutils Testing`_.
244
The review process will ensure that at least one other set of eyeballs
245
& brains sees the code before it enters the core. In addition to the
246
above, the general `Check-ins`_ policy (below) also applies.
248
.. _Docutils Testing: testing.html
254
Changes or additions to the Docutils core and maintenance branches
255
carry a commitment to the Docutils user community. Developers must be
256
prepared to fix and maintain any code they have committed.
258
The Docutils core (``trunk/docutils`` directory) and maintenance
259
branches should always be kept in a stable state (usable and as
260
problem-free as possible). All changes to the Docutils core or
261
maintenance branches must be in `good shape`_, usable_, documented_,
262
tested_, and `reasonably complete`_.
264
* _`Good shape` means that the code is clean, readable, and free of
265
junk code (unused legacy code; by analogy to "junk DNA").
267
* _`Usable` means that the code does what it claims to do. An "XYZ
268
Writer" should produce reasonable XYZ output.
270
* _`Documented`: The more complete the documentation the better.
271
Modules & files must be at least minimally documented internally.
272
`Docutils Front-End Tools`_ should have a new section for any
273
front-end tool that is added. `Docutils Configuration Files`_
274
should be modified with any settings/options defined. For any
275
non-trivial change, the HISTORY.txt_ file should be updated.
277
* _`Tested` means that unit and/or functional tests, that catch all
278
bugs fixed and/or cover all new functionality, have been added to
279
the test suite. These tests must be checked by running the test
280
suite under all supported Python versions, and the entire test suite
281
must pass. See `Docutils Testing`_.
283
* _`Reasonably complete` means that the code must handle all input.
284
Here "handle" means that no input can cause the code to fail (cause
285
an exception, or silently and incorrectly produce nothing).
286
"Reasonably complete" does not mean "finished" (no work left to be
287
done). For example, a writer must handle every standard element
288
from the Docutils document model; for unimplemented elements, it
289
must *at the very least* warn that "Output for element X is not yet
290
implemented in writer Y".
292
If you really want to check code directly into the Docutils core,
293
you can, but you must ensure that it fulfills the above criteria
294
first. People will start to use it and they will expect it to work!
295
If there are any issues with your code, or if you only have time for
296
gradual development, you should put it on a branch or in the sandbox
297
first. It's easy to move code over to the Docutils core once it's
300
It is the responsibility and obligation of all developers to keep the
301
Docutils core and maintenance branches stable. If a commit is made to
302
the core or maintenance branch which breaks any test, the solution is
303
simply to revert the change. This is not vindictive; it's practical.
304
We revert first, and discuss later.
306
Docutils will pursue an open and trusting policy for as long as
307
possible, and deal with any aberrations if (and hopefully not when)
308
they happen. We'd rather see a torrent of loose contributions than
309
just a trickle of perfect-as-they-stand changes. The occasional
310
mistake is easy to fix. That's what Subversion is for!
312
.. _Docutils Front-End Tools: ../user/tools.html
313
.. _Docutils Configuration Files: ../user/config.html
314
.. _HISTORY.txt: ../../HISTORY.txt
320
Docutils version numbering uses a ``major.minor.micro`` scheme (x.y.z;
323
**Major releases** (x.0, e.g. 1.0) will be rare, and will represent
324
major changes in API, functionality, or commitment. For example, as
325
long as the major version of Docutils is 0, it is to be considered
326
*experimental code*. When Docutils reaches version 1.0, the major
327
APIs will be considered frozen and backward compatibility will become
328
of paramount importance.
330
Releases that change the minor number (x.y, e.g. 0.5) will be
331
**feature releases**; new features from the `Docutils core`_ will be
334
Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
335
**bug-fix releases**. No new features will be introduced in these
336
releases; only bug fixes off of `maintenance branches`_ will be
339
This policy was adopted in October 2005, and will take effect with
340
Docutils version 0.4. Prior to version 0.4, Docutils didn't have an
341
official version numbering policy, and micro releases contained both
342
bug fixes and new features.
345
http://svn.berlios.de/viewcvs/docutils/trunk/docutils/
346
.. _maintenance branches:
347
http://svn.berlios.de/viewcvs/docutils/branches/
353
Snapshot tarballs will be generated regularly from
355
* the Docutils core, representing the current cutting-edge state of
358
* each active maintenance branch, for bug fixes;
360
* each development branch, representing the unstable
361
seat-of-your-pants bleeding edge.
363
The ``sandbox/infrastructure/docutils-update`` shell script, run as an
364
hourly cron job on the BerliOS server, is responsible for
365
automatically generating the snapshots and updating the web site. See
366
the `web site docs <website.html>`__.
369
Setting Up For Docutils Development
370
===================================
372
When making changes to the code, testing is a must. The code should
373
be run to verify that it produces the expected results, and the entire
374
test suite should be run too. The modified Docutils code has to be
375
accessible to Python for the tests to have any meaning. There are two
376
ways to keep the Docutils code accessible during development:
378
1. Update your ``PYTHONPATH`` environment variable so that Python
379
picks up your local working copy of the code. This is the
382
We'll assume that the Docutils trunk is checked out under your
383
~/projects/ directory as follows::
385
svn co svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils/trunk \
388
For the bash shell, add this to your ``~/.profile``::
390
PYTHONPATH=$HOME/projects/docutils/docutils
391
PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras
394
The first line points to the directory containing the ``docutils``
395
package. The second line adds the directory containing the
396
third-party modules Docutils depends on. The third line exports
397
this environment variable. You may also wish to add the ``tools``
398
directory to your ``PATH``::
400
PATH=$PATH:$HOME/projects/docutils/docutils/tools
403
2. Before you run anything, every time you make a change, reinstall
406
python setup.py install
410
This method is **not** recommended for day-to-day development;
411
it's too easy to forget. Confusion inevitably ensues.
413
If you install Docutils this way, Python will always pick up the
414
last-installed copy of the code. If you ever forget to
415
reinstall the "docutils" package, Python won't see your latest
418
A useful addition to the ``docutils`` top-level directory in branches
419
and alternate copies of the code is a ``set-PATHS`` file
420
containing the following lines::
423
export PYTHONPATH=$PWD:$PWD/extras
424
export PATH=$PWD/tools:$PATH
426
Open a shell for this branch, ``cd`` to the ``docutils`` top-level
427
directory, and "source" this file. For example, using the bash
430
$ cd some-branch/docutils
437
Developers are recommended to subscribe to all `Docutils mailing
440
.. _Docutils mailing lists: ../user/mailing-lists.html
446
There is a development wiki at http://docutils.python-hosting.com/ as
447
a scratchpad for transient notes. Please use the repository for
448
permament document storage.
454
The `sandbox directory`_ is a place to play around, to try out and
455
share ideas. It's a part of the Subversion repository but it isn't
456
distributed as part of Docutils releases. Feel free to check in code
457
to the sandbox; that way people can try it out but you won't have to
458
worry about it working 100% error-free, as is the goal of the Docutils
459
core. Each developer who wants to play in the sandbox should create
460
either a project-specific subdirectory or personal subdirectory
461
(suggested name: SourceForge ID, nickname, or given name + family
462
initial). It's OK to make a mess in your personal space! But please,
465
Please update the `sandbox README`_ file with links and a brief
466
description of your work.
468
In order to minimize the work necessary for others to install and try
469
out new, experimental components, the following sandbox directory
470
structure is recommended::
473
project_name/ # For a collaborative project.
474
# Structure as in userid/component_name below.
475
userid/ # For personal space.
476
component_name/ # A verbose name is best.
477
README.txt # Please explain the requirements,
478
# purpose/goals, and usage.
481
component.py # The component is a single module.
482
# *OR* (but *not* both)
483
component/ # The component is a package.
484
__init__.py # Contains the Reader/Writer class.
485
other1.py # Other modules and data files used
486
data.txt # by this component.
490
tools/ # For front ends etc.
492
setup.py # Use Distutils to install the component
493
# code and tools/ files into the right
494
# places in Docutils.
496
Some sandbox projects are destined to become Docutils components once
497
completed. Others, such as add-ons to Docutils or applications of
498
Docutils, graduate to become `parallel projects`_.
500
.. _sandbox README: http://docutils.sf.net/sandbox/README.html
501
.. _sandbox directory:
502
http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/
505
.. _parallel project:
510
Parallel projects contain useful code that is not central to the
511
functioning of Docutils. Examples are specialized add-ons or
512
plug-ins, and applications of Docutils. They use Docutils, but
513
Docutils does not require their presence to function.
515
An official parallel project will have its own directory beside (or
516
parallel to) the main ``docutils`` directory in the Subversion
517
repository. It can have its own web page in the
518
docutils.sourceforge.net domain, its own file releases and
519
downloadable snapshots, and even a mailing list if that proves useful.
520
However, an official parallel project has implications: it is expected
521
to be maintained and continue to work with changes to the core
524
A parallel project requires a project leader, who must commit to
525
coordinate and maintain the implementation:
527
* Answer questions from users and developers.
528
* Review suggestions, bug reports, and patches.
529
* Monitor changes and ensure the quality of the code and
531
* Coordinate with Docutils to ensure interoperability.
532
* Put together official project releases.
534
Of course, related projects may be created independently of Docutils.
535
The advantage of a parallel project is that the SourceForge
536
environment and the developer and user communities are already
537
established. Core Docutils developers are available for consultation
538
and may contribute to the parallel project. It's easier to keep the
539
projects in sync when there are changes made to the core Docutils
546
indent-tabs-mode: nil
547
sentence-end-double-space: t
added
removed
docs/dev/policies.txt
