diff options
Diffstat (limited to 'docutils/docs/dev/policies.txt')
| -rw-r--r-- | docutils/docs/dev/policies.txt | 422 |
1 files changed, 0 insertions, 422 deletions
diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt deleted file mode 100644 index 99eade2e7..000000000 --- a/docutils/docs/dev/policies.txt +++ /dev/null @@ -1,422 +0,0 @@ -=========================== - 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: |