diff options
Diffstat (limited to 'docs/dev/policies.txt')
| -rw-r--r-- | docs/dev/policies.txt | 422 |
1 files changed, 422 insertions, 0 deletions
diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt new file mode 100644 index 000000000..99eade2e7 --- /dev/null +++ b/docs/dev/policies.txt @@ -0,0 +1,422 @@ +=========================== + Docutils Project Policies +=========================== + +:Author: David Goodger; open to all Docutils developers +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This document has been placed in the public domain. + +.. contents:: + +Docutils is a meritocracy based on code contribution and lots of +discussion [#bcs]_. A few quotes sum up the policies of the Docutils +project. The IETF's classic credo (by MIT professor Dave Clark) is an +ideal we can aspire to: + + We reject: kings, presidents, and voting. We believe in: rough + consensus and running code. + +As architect, chief cook and bottle-washer, I currently function as +BDFN (Benevolent Dictator For Now), but I would happily abdicate the +throne given a suitable candidate. Any takers? + +Eric S. Raymond, anthropologist of the hacker subculture, writes in +his essay `The Magic Cauldron`_: + + The number of contributors [to] projects is strongly and inversely + correlated with the number of hoops each project makes a user go + through to contribute. + + .. _The Magic Cauldron: + http://www.tuxedo.org/~esr/writings/magic-cauldron/ + +Therefore, we will endeavour to keep the barrier to entry as low as +possible. The policies below should not be thought of as barriers, +but merely as a codification of experience to date. These are "best +practices", not absolutes; exceptions are expected, tolerated, and +used as a source of improvement. Feedback and criticism is welcome. + +As for control issues, Emmett Plant (CEO of the Xiph.org Foundation, +originators of Ogg Vorbis) put it well when he said: + + Open source dictates that you lose a certain amount of control + over your codebase, and that's okay with us. + +.. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion + project <http://www.red-bean.com/sussman/svn-anti-fud.html>`__. + + +Python Coding Conventions +========================= + +These are the conventions I use in my own code. Contributed code will +not be refused merely because it does not strictly adhere to these +conditions; as long as it's internally consistent, clean, and correct, +it probably will be accepted. But don't be surprised if the +"offending" code gets fiddled over time to conform to these +conventions. + +The Docutils project shall follow the generic coding conventions as +specified in the `Style Guide for Python Code`_ and `Docstring +Conventions`_ PEPs, with the following clarifications and extensions: + +* 4 spaces per indentation level. No tabs. + +* Use only ASCII, no 8-bit strings. See `Docutils + Internationalization`_. + +* No one-liner compound statements (i.e., no ``if x: return``: use two + lines & indentation), except for degenerate class or method + definitions (i.e., ``class X: pass`` is O.K.). + +* Lines should be no more than 78 characters long. + +* Use "StudlyCaps" for class names (except for element classes in + docutils.nodes). + +* Use "lowercase" or "lowercase_with_underscores" for function, + method, and variable names. For short names, maximum two words, + joined lowercase may be used (e.g. "tagname"). For long names with + three or more words, or where it's hard to parse the split between + two words, use lowercase_with_underscores (e.g., + "note_explicit_target", "explicit_target"). If in doubt, use + underscores. + +* Avoid functional constructs (lambda, filter, map, etc.). Use list + comprehensions instead. + +* Avoid ``from __future__ import`` constructs; we don't want them in + production code. + +* Use 'single quotes' for string literals, and """triple double + quotes""" for docstrings. + +.. _Style Guide for Python Code: + http://www.python.org/peps/pep-0008.html +.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html +.. _Docutils Internationalization: ../howto/i18n.html#python-code + + +Copyrights and Licensing +======================== + +The majority of the Docutils project code and documentation has been +placed in the public domain. Unless clearly and explicitly indicated +otherwise, any patches (modifications to existing files) submitted to +the project for inclusion (via Subversion, SourceForge trackers, +mailing lists, or private email) are assumed to be in the public +domain as well. + +Any new files contributed to the project should clearly state their +intentions regarding copyright, in one of the following ways: + +* Public domain (preferred): include the statement "This + module/document has been placed in the public domain." + +* Copyright & open source license: include a copyright notice, along + with either an embedded license statement, a reference to an + accompanying license file, or a license URL. + +One of the goals of the Docutils project, once complete, is to be +incorporated into the Python standard library. At that time copyright +of the Docutils code will be assumed by or transferred to the Python +Software Foundation (PSF), and will be released under Python's +license. If the copyright/license option is chosen for new files, the +license should be compatible with Python's current license, and the +author(s) of the files should be willing to assign copyright to the +PSF. + + +Subversion Check-ins +==================== + +Please see the `repository documentation`_ for details on how to +access Docutils' Subversion repository. Anyone can access the +repository anonymously. Only project developers can make changes. +Also see `Setting Up For Docutils Development`_ below for more info. + +.. _repository documentation: repository.html + +Unless you really *really* know what you're doing, please limit your +Subversion commands to ``svn checkout``, ``svn commit``, and ``svn +add``. Do **NOT** use ``svn import`` unless you're absolutely sure +you know what you're doing. Even then, grab a copy of the `nightly +repository tarball`_, set it up on your own machine, and experiment +*there* first (but remove hooks/post-commit first). + +The `main source tree`_ ("trunk/docutils" directory) should always be +kept in a stable state (usable and as problem-free as possible). The +Docutils project shall follow the `Python Check-in Policies`_ (as +applicable), with particular emphasis as follows: + +* Before checking in any changes, run the entire Docutils test suite + to be sure that you haven't broken anything. From a shell:: + + cd docutils/test + ./alltests.py + + Docutils currently supports Python 2.1 [#py21]_ or later, with some + things only working (and being tested) on Python 2.3+. Therefore, + you should actually have Pythons 2.1 [#py21]_, 2.2 and 2.3 installed + and always run the tests on all of them. (A good way to do that is + to always run the test suite through a short script that runs + ``alltests.py`` under each version of Python.) If you can't afford + intalling 3 Python versions, the edge cases (2.1 and 2.3) should + cover most of it. + + .. [#py21] Python 2.1 may be used providing the compiler package is + installed. The compiler package can be found in the Tools/ + directory of Python 2.1's source distribution. + + Good resources covering the differences between Python versions: + + * `What's New in Python 2.2`__ + * `What's New in Python 2.3`__ + * `What's New in Python 2.4`__ + * `PEP 290 - Code Migration and Modernization`__ + + __ http://www.python.org/doc/2.2.3/whatsnew/whatsnew22.html + __ http://www.python.org/doc/2.3.5/whatsnew/whatsnew23.html + __ http://www.python.org/doc/2.4.1/whatsnew/whatsnew24.html + __ http://www.python.org/peps/pep-0290.html + +* When adding new functionality (or fixing bugs), be sure to add test + cases to the test suite. Practise test-first programming; it's fun, + it's addictive, and it works! + +* The `sandbox directory`_ is the place to put new, incomplete or + experimental code. See `Additions to Docutils`_ and `The Sandbox`_ + below. + +* For bugs or omissions that have an obvious fix and can't possibly + mess up anything else, go right ahead and check it in directly. + +* For larger changes, use your best judgement. If you're unsure of + the impact, or feel that you require advice or approval, patches or + `the sandbox`_ are the way to go. + +Docutils will pursue an open and trusting policy for as long as +possible, and deal with any aberrations if (and hopefully not when) +they happen. I'd rather see a torrent of loose contributions than +just a trickle of perfect-as-they-stand changes. The occasional +mistake is easy to fix. That's what Subversion is for. + +.. _main source tree: + http://svn.berlios.de/viewcvs/docutils/trunk/docutils/ +.. _Python Check-in Policies: http://www.python.org/dev/tools.html +.. _sandbox directory: + http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/ +.. _nightly repository tarball: + http://svn.berlios.de/svndumps/docutils-repos.gz + + +Additions to Docutils +--------------------- + +Additions to the project, such as new components, should be developed +in the `sandbox directory`_ until they're in `good shape`_, usable_, +documented_, and `reasonably complete`_. Adding to the `main source +tree`_ or to a `parallel project`_ implies a commitment to the +Docutils user community. + +* Why the sandbox? + + Developers should be able to try out new components while they're + being developed for addition to main source tree. See `The + Sandbox`_ below. + +* _`Good shape` means that the component code is clean, readable, and + free of junk code (unused legacy code; by analogy with "junk DNA"). + +* _`Usable` means that the code does what it claims to do. An "XYZ + Writer" should produce reasonable XYZ. + +* _`Documented`: The more the better. The modules/files must be at + least minimally documented internally. `Docutils Front-End Tools`_ + should have a new section for any front-end tool that is added. + `Docutils Configuration Files`_ should be modified with any + settings/options defined. + +* _`Reasonably complete` means that the code must handle all input. + Here "handle" means that no input can cause the code to fail (cause + an exception, or silently and incorrectly produce nothing). + "Reasonably complete" does not mean "finished" (no work left to be + done). For example, a writer must handle every standard element + from the Docutils document model; for unimplemented elements, it + must *at the very least* warn that "Output for element X is not yet + implemented in writer Y". + +If you really want to check code into the main source tree, you can, +but you'll have to be prepared to work on it intensively and complete +it quickly. People will start to use it and they will expect it to +work! If there are any issues with your code, or if you only have +time for gradual development, you should put it in the sandbox first. +It's easy to move code over to the main source tree once it's closer +to completion. + +.. _Docutils Front-End Tools: ../user/tools.html +.. _Docutils Configuration Files: ../user/config.html + + +Setting Up For Docutils Development +----------------------------------- + +When making changes to the code, good developers always test their +changes. That means running the code to check that it produces the +expected results, and running the test suite too. The modified +Docutils code has to be accessible to Python for the tests to have any +meaning. There are two ways to keep the Docutils code accessible: + +* Update your ``PYTHONPATH`` environment variable so that Python picks + up your local working copy of the code. This is the recommended + method. + + For the bash shell and Docutils checked out from Subversion in + ``~/projects/docutils/``, add this to your ``~/.profile``:: + + PYTHONPATH=$HOME/projects/docutils/docutils + PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras + export PYTHONPATH + + The first line points to the directory containing the ``docutils`` + package. The second line adds the directory containing the + third-party modules Docutils depends on. The third line exports + this environment variable. You may also wish to add the ``tools`` + directory to your ``PATH``:: + + PATH=$PATH:$HOME/projects/docutils/docutils/tools + +* Before you run anything, every time you make a change, reinstall + Docutils:: + + python setup.py install + + .. CAUTION:: + + This method is **not** recommended for day-to-day development; + it's too easy to forget. Confusion inevitably ensues. + + If you install Docutils this way, Python will always pick up the + last-installed copy of the code. If you ever forget to reinstall + the "docutils" package, Python won't see your latest changes. + + +Mailing Lists +============= + +Developers should subscribe to the mailing lists: + +* The `Python Documentation Special Interest Group (Doc-SIG) mailing + list`__ for high-level discussions on syntax, strategy, and design + (email to Doc-SIG@python.org). +* Docutils-develop__, for implementation discussions + (email to docutils-develop@lists.sourceforge.net). +* Docutils-checkins__, to monitor Subversion check-in messages + (automatically generated; normally read-only). +* Docutils-users__, to monitor and help out with usage issues and bug + reports. + +__ http://mail.python.org/mailman/listinfo/doc-sig +__ http://lists.sourceforge.net/lists/listinfo/docutils-develop +__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins +__ http://lists.sourceforge.net/lists/listinfo/docutils-users + + +The Sandbox +=========== + +The `sandbox directory`_ is a place to play around, to try out and +share ideas. It's a part of the Subversion repository but it isn't +distributed as part of Docutils releases. Feel free to check in code +to the sandbox; that way people can try it out but you won't have to +worry about it working 100% error-free, as is the goal of the `main +source tree`_. Each developer who wants to play in the sandbox should +create either a project-specific subdirectory or personal subdirectory +(suggested name: SourceForge ID, nickname, or given name + family +initial). It's OK to make a mess! But please, play nice. + +Please update the `sandbox README`_ file with links and a brief +description of your work. + +In order to minimize the work necessary for others to install and try +out new, experimental components, the following sandbox directory +structure is recommended:: + + sandbox/ + project_name/ # For a project where you invite contributions. + # Structure as in userid/component_name below. + userid/ # For personal space. + component_name/ # A verbose name is best. + README.txt # Please explain requirements, + # purpose/goals, and usage. + docs/ + ... + component.py # The component is a single module. + # *OR* (but *not* both) + component/ # The component is a package. + __init__.py # Contains the Reader/Writer class. + other1.py # Other modules and data files used + data.txt # by this component. + ... + test/ # Test suite. + ... + tools/ # For front ends etc. + ... + setup.py # Use Distutils to install the component + # code and tools/ files into the right + # places in Docutils. + +Some sandbox projects are destined to become Docutils components once +completed. Others, such as add-ons to Docutils or applications of +Docutils, graduate to become `parallel projects`_. + +.. _sandbox README: http://docutils.sf.net/sandbox/README.html + + +.. _parallel project: + +Parallel Projects +================= + +Parallel projects contain useful code that is not central to the +functioning of Docutils. Examples are specialized add-ons or +plug-ins, and applications of Docutils. They use Docutils, but +Docutils does not require their presence to function. + +An official parallel project will have its own directory beside (or +parallel to) the main ``docutils`` directory in the Subversion +repository. It can have its own web page in the +docutils.sourceforge.net domain, its own file releases and +downloadable snapshots, and even a mailing list if that proves useful. +However, an official parallel project has implications: it is expected +to be maintained and continue to work with changes to the core +Docutils. + +A parallel project requires a project leader, who must commit to +coordinate and maintain the implementation: + +* Answer questions from users and developers. +* Review suggestions, bug reports, and patches. +* Monitor changes and ensure the quality of the code and + documentation. +* Coordinate with Docutils to ensure interoperability. +* Put together official project releases. + +Of course, related projects may be created independently of Docutils. +The advantage of a parallel project is that the SourceForge +environment and the developer and user communities are already +established. Core Docutils developers are available for consultation +and may contribute to the parallel project. It's easier to keep the +projects in sync when there are changes made to the core Docutils +code. + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: |