Revision: 7380
http://docutils.svn.sourceforge.net/docutils/?rev=7380&view=rev
Author: milde
Date: 2012-03-10 22:46:07 +0000 (Sat, 10 Mar 2012)
Log Message:
-----------
Added "How to get a new feature into Docutils".
Modified Paths:
--------------
trunk/docutils/docs/dev/policies.txt
Modified: trunk/docutils/docs/dev/policies.txt
===================================================================
--- trunk/docutils/docs/dev/policies.txt 2012-03-07 02:00:39 UTC (rev 7379)
+++ trunk/docutils/docs/dev/policies.txt 2012-03-10 22:46:07 UTC (rev 7380)
@@ -48,6 +48,65 @@
http://www.catb.org/~esr/writings/magic-cauldron/
+How to get a new feature into Docutils
+========================================
+
+Question:
+ I would very much like to have this new feature in the Docutils core.
+ What exactly do I have to do to make this possible?
+
+* Present your idea at the Docutils-develop_ mailing list,
+
+ +1 usually triggers a fast response,
+ -1 may be forgotten later,
+
+ and/or file a feature request at the `docutils tracker`_
+
+ +1 there is a permanent record,
+ -1 it may stay forgotten among all the other feature requests.
+
+
+* Convince a Docutils developer that this is a valuable addition worth the
+ effort.
+
+* Contribute. The developers will make sure that the contribution fits
+ nicely into Docutils (cf. the `review criteria`_). This might involve
+ discussing (and compromising on) design and implementation details. It
+ might also lead to the conclusion that the addition fits better in `the
+ sandbox`_ than in the Docutils core.
+
+* Be patient, and be persistent. None of us are paid to do this,
+ it's all in our spare time -- which is precious and rare.
+
+How to make code contributions that are easily accepted:
+
+* Have a look at the `Python coding conventions`_ and `documentation
+ conventions`_ below.
+
+* **Prepare test cases.** This vastly helps when integrating new code. Test
+ cases are also examples and showcases for new features. See `Docutils
+ Testing`_ for a description of the test suite in ``docutils/test/``.
+
+ Ensure the addition works with all supported Python versions
+ (2.3 ... 3.2).
+
+* Look at the Docutils sources to see how similar features are implemented,
+ learn to do it "the Docutils way".
+
+* Prepare the a patch or an addition to the existing documentation.
+ Include links.
+
+* If you are familiar with version control, consider creating a `feature
+ branch`_ in a Docutils repository_ checkout. (Working with branches is
+ *much* easier with git_. You can get a git clone of the repository from
+ http://repo.or.cz/w/docutils.git or with git-svn.)
+
+.. _docutils-develop: ../user/mailing-lists.html#docutils-develop
+.. _docutils tracker: http://sourceforge.net/tracker/?group_id=38414
+.. _git: http://git-scm.com/
+.. _Docutils testing: testing.html
+
+
Python Coding Conventions
=========================
@@ -217,9 +276,11 @@
.. _pypi: http://pypi.python.org/pypi?:action=browse&c=54
-Subversion Repository
-=====================
+.. _Subversion Repository:
+Repository
+==========
+
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.
@@ -256,6 +317,9 @@
but they may be used. It is up to the discretion of project
developers to decide which mechanism to use for each case.
+.. _feature branches:
+.. _feature branch:
+
Feature additions and API changes will be done in **feature
branches**. Feature branches will not be managed in any way.
Frequent small checkins are encouraged here. Feature branches must be
@@ -290,9 +354,7 @@
& brains sees the code before it enters the core. In addition to the
above, the general `Check-ins`_ policy (below) also applies.
-.. _Docutils Testing: testing.html
-
Check-ins
---------
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|