/usr/share/doc/docutils-doc/docs/dev/policies.html is in docutils-doc 0.14+dfsg-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 | <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>Docutils Project Policies</title>
<meta name="author" content="David Goodger; open to all Docutils developers" />
<meta name="date" content="2017-06-23" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="docutils-project-policies">
<h1 class="title">Docutils Project Policies</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger; open to all Docutils developers</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2017-06-23</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>8123</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#how-to-get-a-new-feature-into-docutils" id="id3">How to get a new feature into Docutils</a></li>
<li><a class="reference internal" href="#python-coding-conventions" id="id4">Python Coding Conventions</a></li>
<li><a class="reference internal" href="#documentation-conventions" id="id5">Documentation Conventions</a></li>
<li><a class="reference internal" href="#copyrights-and-licensing" id="id6">Copyrights and Licensing</a><ul>
<li><a class="reference internal" href="#clause-bsd-license" id="id7">2-Clause BSD license</a></li>
</ul>
</li>
<li><a class="reference internal" href="#repository" id="id8">Repository</a><ul>
<li><a class="reference internal" href="#branches" id="id9">Branches</a><ul>
<li><a class="reference internal" href="#review-criteria" id="id10">Review Criteria</a></li>
</ul>
</li>
<li><a class="reference internal" href="#check-ins" id="id11">Check-ins</a></li>
</ul>
</li>
<li><a class="reference internal" href="#version-numbering" id="id12">Version Numbering</a></li>
<li><a class="reference internal" href="#snapshots" id="id13">Snapshots</a></li>
<li><a class="reference internal" href="#setting-up-for-docutils-development" id="id14">Setting Up For Docutils Development</a></li>
<li><a class="reference internal" href="#mailing-lists" id="id15">Mailing Lists</a></li>
<li><a class="reference internal" href="#the-wiki" id="id16">The Wiki</a></li>
<li><a class="reference internal" href="#extensions-and-related-projects" id="id17">Extensions and Related Projects</a><ul>
<li><a class="reference internal" href="#the-sandbox" id="id18">The Sandbox</a></li>
<li><a class="reference internal" href="#parallel-projects" id="id19">Parallel Projects</a></li>
<li><a class="reference internal" href="#other-related-projects" id="id20">Other related projects</a></li>
</ul>
</li>
</ul>
</div>
<p>The Docutils project group is a meritocracy based on code contribution
and lots of discussion <a class="footnote-reference" href="#bcs" id="id1">[1]</a>. 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:</p>
<blockquote>
We reject: kings, presidents, and voting. We believe in: rough
consensus and running code.</blockquote>
<p>As architect, chief cook and bottle-washer, David Goodger currently
functions as BDFN (Benevolent Dictator For Now). (But he would
happily abdicate the throne given a suitable candidate. Any takers?)</p>
<p>Eric S. Raymond, anthropologist of the hacker subculture, writes in
his essay <a class="reference external" href="http://www.catb.org/~esr/writings/magic-cauldron/">The Magic Cauldron</a>:</p>
<blockquote>
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.</blockquote>
<p>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";
guidelines, not absolutes. Exceptions are expected, tolerated, and
used as a source of improvement. Feedback and criticism is welcome.</p>
<p>As for control issues, Emmett Plant (CEO of the Xiph.org Foundation,
originators of Ogg Vorbis) put it well when he said:</p>
<blockquote>
Open source dictates that you lose a certain amount of control
over your codebase, and that's okay with us.</blockquote>
<table class="docutils footnote" frame="void" id="bcs" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Phrase borrowed from <a class="reference external" href="http://www.red-bean.com/sussman/svn-anti-fud.html">Ben Collins-Sussman of the Subversion
project</a>.</td></tr>
</tbody>
</table>
<div class="section" id="how-to-get-a-new-feature-into-docutils">
<h1><a class="toc-backref" href="#id3">How to get a new feature into Docutils</a></h1>
<dl class="docutils">
<dt>Question:</dt>
<dd>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?</dd>
</dl>
<ul>
<li><p class="first">Present your idea at the <a class="reference external" href="../user/mailing-lists.html#docutils-develop">Docutils-develop</a> mailing list,</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">usually triggers a fast response,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">may be forgotten later,</p>
</td></tr>
</tbody>
</table>
<p>and/or file a ticket at Docutils' <a class="reference external" href="http://sourceforge.net/p/docutils/feature-requests/">feature request tracker</a>.</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">there is a permanent record,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">it may stay forgotten among all the other feature requests.</p>
</td></tr>
</tbody>
</table>
</li>
<li><p class="first">Convince a Docutils developer that this is a valuable addition worth the
effort.</p>
</li>
<li><p class="first">Contribute. The developers will make sure that the contribution fits
nicely into Docutils (cf. the <a class="reference internal" href="#review-criteria">review criteria</a>). 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
<a class="reference internal" href="#extensions-and-related-projects">extensions and related projects</a>.</p>
</li>
<li><p class="first">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.</p>
</li>
</ul>
<p>How to make code contributions that are easily accepted:</p>
<ul>
<li><p class="first">Have a look at the <a class="reference internal" href="#python-coding-conventions">Python coding conventions</a> and <a class="reference internal" href="#documentation-conventions">documentation
conventions</a> below.</p>
</li>
<li><p class="first"><strong>Prepare test cases.</strong> This vastly helps when integrating new code. Test
cases are also examples and showcases for new features. See <a class="reference external" href="testing.html">Docutils
Testing</a> for a description of the test suite in <tt class="docutils literal">docutils/test/</tt>.</p>
<p>Ensure the addition works with all <a class="reference external" href="../../README.html#requirements">supported Python versions</a>.</p>
</li>
<li><p class="first">Look at the Docutils sources to see how similar features are implemented,
learn to do it "the Docutils way".</p>
</li>
<li><p class="first">Prepare the a patch or an addition to the existing documentation.
Include links.</p>
</li>
<li><p class="first">If you are familiar with version control, consider creating a <a class="reference internal" href="#feature-branch">feature
branch</a> in a Docutils <a class="reference internal" href="#repository">repository</a> checkout. (Working with branches is
<em>much</em> easier with <a class="reference external" href="http://git-scm.com/">git</a>. You can get a git clone of the repository from
<a class="reference external" href="http://repo.or.cz/w/docutils.git">http://repo.or.cz/w/docutils.git</a> or with git-svn.)</p>
</li>
</ul>
</div>
<div class="section" id="python-coding-conventions">
<h1><a class="toc-backref" href="#id4">Python Coding Conventions</a></h1>
<p>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.</p>
<p>The Docutils project shall follow the generic coding conventions as
specified in the <a class="reference external" href="http://www.python.org/peps/pep-0008.html">Style Guide for Python Code</a> and <a class="reference external" href="http://www.python.org/peps/pep-0257.html">Docstring
Conventions</a> PEPs, summarized, clarified, and extended as follows:</p>
<ul class="simple">
<li>4 spaces per indentation level. No hard tabs.</li>
<li>Use only 7-bit ASCII, no 8-bit strings. See <a class="reference external" href="../howto/i18n.html#python-code">Docutils
Internationalization</a>.</li>
<li>No one-liner compound statements (i.e., no <tt class="docutils literal">if x: return</tt>: use two
lines & indentation), except for degenerate class or method
definitions (i.e., <tt class="docutils literal">class X: pass</tt> is OK.).</li>
<li>Lines should be no more than 78 characters long.</li>
<li>Use "StudlyCaps" for class names (except for element classes in
docutils.nodes).</li>
<li>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.</li>
<li>Avoid lambda expressions, which are inherently difficult to
understand. Named functions are preferable and superior: they're
faster (no run-time compilation), and well-chosen names serve to
document and aid understanding.</li>
<li>Avoid functional constructs (filter, map, etc.). Use list
comprehensions instead.</li>
<li>Avoid <tt class="docutils literal">from __future__ import</tt> constructs. They are inappropriate
for production code.</li>
<li>Use 'single quotes' for string literals, and """triple double
quotes""" for docstrings.</li>
</ul>
</div>
<div class="section" id="documentation-conventions">
<h1><a class="toc-backref" href="#id5">Documentation Conventions</a></h1>
<ul>
<li><p class="first">Docutils documentation is written using reStructuredText, of course.</p>
</li>
<li><p class="first">Use 7-bit ASCII if at all possible, and Unicode substitutions when
necessary.</p>
</li>
<li><p class="first">Use the following section title adornment styles:</p>
<pre class="literal-block">
================
Document Title
================
--------------------------------------------
Document Subtitle, or Major Division Title
--------------------------------------------
Section
=======
Subsection
----------
Sub-Subsection
``````````````
Sub-Sub-Subsection
..................
</pre>
</li>
<li><p class="first">Use two blank lines before each section/subsection/etc. title. One
blank line is sufficient between immediately adjacent titles.</p>
</li>
<li><p class="first">Add a bibliographic field list immediately after the document
title/subtitle. See the beginning of this document for an example.</p>
</li>
<li><p class="first">Add an Emacs "local variables" block in a comment at the end of the
document. See the end of this document for an example.</p>
</li>
</ul>
</div>
<div class="section" id="copyrights-and-licensing">
<h1><a class="toc-backref" href="#id6">Copyrights and Licensing</a></h1>
<p>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.</p>
<p>Any new files contributed to the project should clearly state their
intentions regarding copyright, in one of the following ways:</p>
<ul>
<li><p class="first">Public domain (preferred): include the statement "This
module/document has been placed in the public domain."</p>
</li>
<li><p class="first">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.</p>
<p>The license should be well known, simple and compatible with other
open source software licenses. To keep the number of different
licenses at a minimum, using the <a class="reference internal" href="#clause-bsd-license">2-Clause BSD license</a>
is recommended.</p>
</li>
</ul>
<div class="section" id="clause-bsd-license">
<h2><a class="toc-backref" href="#id7">2-Clause BSD license</a></h2>
<p>(also known as "Simplified" or <cite>FreeBSD license</cite>)</p>
<blockquote>
<p>If you want a simple, permissive non-copyleft free software license, the
FreeBSD license is a reasonable choice. However, please don't call it a
“BSD” or “BSD-style” license, because that is likely to cause confusion
which could lead to use of the flawed original BSD license.</p>
<p class="attribution">—<a class="reference external" href="http://www.gnu.org/licenses/license-list.html">Various Licenses and Comments about Them</a></p>
</blockquote>
<dl class="docutils">
<dt>Pros:</dt>
<dd><ul class="first last simple">
<li>clear wording, structured text</li>
<li>license used by the closely related Sphinx project</li>
<li>"2-Clause BSD license" is a non-ambiguous name, used by both, OSI and
GNU.</li>
</ul>
</dd>
<dt>References:</dt>
<dd><ul class="first last simple">
<li><a class="reference external" href="http://www.freebsd.org/copyright/freebsd-license.html">http://www.freebsd.org/copyright/freebsd-license.html</a></li>
<li><a class="reference external" href="http://www.opensource.org/licenses/BSD-2-Clause">http://www.opensource.org/licenses/BSD-2-Clause</a></li>
<li><a class="reference external" href="http://www.spdx.org/licenses/BSD-2-Clause">http://www.spdx.org/licenses/BSD-2-Clause</a></li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section" id="repository">
<span id="subversion-repository"></span><h1><a class="toc-backref" href="#id8">Repository</a></h1>
<p>Please see the <a class="reference external" href="repository.html">repository documentation</a> for details on how to
access Docutils' Subversion repository. Anyone can access the
repository anonymously. Only project developers can make changes.
(If you would like to become a project developer, just ask!) Also see
<a class="reference internal" href="#setting-up-for-docutils-development">Setting Up For Docutils Development</a> below for some useful info.</p>
<p>Unless you really <em>really</em> know what you're doing, please do <em>not</em> use
<tt class="docutils literal">svn import</tt>. It's quite easy to mess up the repository with an
import.</p>
<div class="section" id="branches">
<h2><a class="toc-backref" href="#id9">Branches</a></h2>
<p>(These branch policies go into effect with Docutils 0.4.)</p>
<p>The "docutils" directory of the <strong>trunk</strong> (a.k.a. the <strong>Docutils
core</strong>) is used for active -- but stable, fully tested, and reviewed
-- development.</p>
<p>If we need to cut a bugfix release, we'll create a <strong>maintenance branch</strong>
based on the latest feature release. For example, when Docutils 0.5 is
released, this would be <tt class="docutils literal"><span class="pre">branches/docutils-0.5</span></tt>, any existing 0.4.x
maintenance branches may be retired. Maintenance branches will receive bug
fixes only; no new features will be allowed here.</p>
<p>Obvious and uncontroversial bug fixes <em>with tests</em> can be checked in
directly to the core and to the maintenance branches. Don't forget to
add test cases! Many (but not all) bug fixes will be applicable both
to the core and to the maintenance branches; these should be applied
to both. No patches or dedicated branches are required for bug fixes,
but they may be used. It is up to the discretion of project
developers to decide which mechanism to use for each case.</p>
<p id="feature-branch"><span id="feature-branches"></span>Feature additions and API changes will be done in <strong>feature
branches</strong>. Feature branches will not be managed in any way.
Frequent small checkins are encouraged here. Feature branches must be
discussed on the <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/docutils-develop">docutils-develop mailing list</a> and reviewed before
being merged into the core.</p>
<div class="section" id="review-criteria">
<h3><a class="toc-backref" href="#id10">Review Criteria</a></h3>
<p>Before a new feature, an API change, or a complex, disruptive, or
controversial bug fix can be checked in to the core or into a
maintenance branch, it must undergo review. These are the criteria:</p>
<ul class="simple">
<li>The branch must be complete, and include full documentation and
tests.</li>
<li>There should ideally be one branch merge commit per feature or
change. In other words, each branch merge should represent a
coherent change set.</li>
<li>The code must be stable and uncontroversial. Moving targets and
features under debate are not ready to be merged.</li>
<li>The code must work. The test suite must complete with no failures.
See <a class="reference external" href="testing.html">Docutils Testing</a>.</li>
</ul>
<p>The review process will ensure that at least one other set of eyeballs
& brains sees the code before it enters the core. In addition to the
above, the general <a class="reference internal" href="#check-ins">Check-ins</a> policy (below) also applies.</p>
</div>
</div>
<div class="section" id="check-ins">
<h2><a class="toc-backref" href="#id11">Check-ins</a></h2>
<p>Changes or additions to the Docutils core and maintenance branches
carry a commitment to the Docutils user community. Developers must be
prepared to fix and maintain any code they have committed.</p>
<p>The Docutils core (<tt class="docutils literal">trunk/docutils</tt> directory) and maintenance
branches should always be kept in a stable state (usable and as
problem-free as possible). All changes to the Docutils core or
maintenance branches must be in <a class="reference internal" href="#good-shape">good shape</a>, <a class="reference internal" href="#usable">usable</a>, <a class="reference internal" href="#documented">documented</a>,
<a class="reference internal" href="#tested">tested</a>, and <a class="reference internal" href="#reasonably-complete">reasonably complete</a>.</p>
<ul class="simple">
<li><span class="target" id="good-shape">Good shape</span> means that the code is clean, readable, and free of
junk code (unused legacy code; by analogy to "junk DNA").</li>
<li><span class="target" id="usable">Usable</span> means that the code does what it claims to do. An "XYZ
Writer" should produce reasonable XYZ output.</li>
<li><span class="target" id="documented">Documented</span>: The more complete the documentation the better.
Modules & files must be at least minimally documented internally.
<a class="reference external" href="../user/tools.html">Docutils Front-End Tools</a> should have a new section for any
front-end tool that is added. <a class="reference external" href="../user/config.html">Docutils Configuration Files</a>
should be modified with any settings/options defined. For any
non-trivial change, the <a class="reference external" href="../../HISTORY.txt">HISTORY.txt</a> file should be updated.</li>
<li><span class="target" id="tested">Tested</span> means that unit and/or functional tests, that catch all
bugs fixed and/or cover all new functionality, have been added to
the test suite. These tests must be checked by running the test
suite under all supported Python versions, and the entire test suite
must pass. See <a class="reference external" href="testing.html">Docutils Testing</a>.</li>
<li><span class="target" id="reasonably-complete">Reasonably complete</span> 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 <em>at the very least</em> warn that "Output for element X is not yet
implemented in writer Y".</li>
</ul>
<p>If you really want to check code directly into the Docutils core,
you can, but you must ensure that it fulfills the above criteria
first. 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 on a branch or in the sandbox
first. It's easy to move code over to the Docutils core once it's
complete.</p>
<p>It is the responsibility and obligation of all developers to keep the
Docutils core and maintenance branches stable. If a commit is made to
the core or maintenance branch which breaks any test, the solution is
simply to revert the change. This is not vindictive; it's practical.
We revert first, and discuss later.</p>
<p>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. We'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 version control is for!</p>
</div>
</div>
<div class="section" id="version-numbering">
<h1><a class="toc-backref" href="#id12">Version Numbering</a></h1>
<p>Docutils version numbering uses a <tt class="docutils literal">major.minor.micro</tt> scheme (x.y.z;
for example, 0.4.1).</p>
<p><strong>Major releases</strong> (x.0, e.g. 1.0) will be rare, and will represent major
changes in API, functionality, or commitment. When Docutils reaches version
1.0, the major APIs will be considered frozen and backward compatibility
will become of paramount importance.</p>
<p>Releases that change the minor number (x.y, e.g. 0.5) will be
<strong>feature releases</strong>; new features from the <a class="reference external" href="http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils">Docutils core</a> will be
included.</p>
<p>Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
<strong>bug-fix releases</strong>. No new features will be introduced in these
releases; only bug fixes will be included.</p>
<p>This policy was adopted in October 2005, and will take effect with
Docutils version 0.4. Prior to version 0.4, Docutils didn't have an
official version numbering policy, and micro releases contained both
bug fixes and new features.</p>
<p>See also the <a class="reference external" href="release.html#version-numbers">Docutils Release Procedure</a>, <cite>docutils.__version__</cite> and
<cite>docutils.__version_info__</cite>.</p>
</div>
<div class="section" id="snapshots">
<h1><a class="toc-backref" href="#id13">Snapshots</a></h1>
<p>Snapshot tarballs can be downloaded from the repository (see the "download
snapshot" button in the head of the code listing table).</p>
<ul class="simple">
<li>the <a class="reference external" href="http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils">Docutils core</a>, representing the current cutting-edge state of
development;</li>
<li>the <a class="reference external" href="http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/">sandbox directory</a> with contributed projects and extensions from
<a class="reference internal" href="#the-sandbox">the Sandbox</a>;</li>
</ul>
<!-- * maintenance branches, for bug fixes;
TODO: do we have active maintenance branches?
(the only branch looking like a maintenance branch is
http://sourceforge.net/p/docutils/code/HEAD/tree/branches/docutils-0.4) -->
<ul class="simple">
<li><a class="reference external" href="http://sourceforge.net/p/docutils/code/HEAD/tree/branches/">development branches</a>, representing ongoing development efforts to bring
new features into Docutils.</li>
</ul>
</div>
<div class="section" id="setting-up-for-docutils-development">
<h1><a class="toc-backref" href="#id14">Setting Up For Docutils Development</a></h1>
<p>When making changes to the code, testing is a must. The code should
be run to verify that it produces the expected results, and the entire
test suite should be run 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 during development:</p>
<ol class="arabic">
<li><p class="first">Update your <tt class="docutils literal">PYTHONPATH</tt> environment variable so that Python
picks up your local working copy of the code. This is the
recommended method.</p>
<p>We'll assume that the Docutils trunk is checked out under your
~/projects/ directory as follows:</p>
<pre class="literal-block">
svn co https://<user>@docutils.svn.sourceforge.net/svnroot/docutils/trunk \
docutils
</pre>
<p>For the bash shell, add this to your <tt class="docutils literal"><span class="pre">~/.profile</span></tt>:</p>
<pre class="literal-block">
PYTHONPATH=$HOME/projects/docutils/docutils
PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras
export PYTHONPATH
</pre>
<p>The first line points to the directory containing the <tt class="docutils literal">docutils</tt>
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 <tt class="docutils literal">tools</tt>
directory to your <tt class="docutils literal">PATH</tt>:</p>
<pre class="literal-block">
PATH=$PATH:$HOME/projects/docutils/docutils/tools
export PATH
</pre>
</li>
<li><p class="first">Before you run anything, every time you make a change, reinstall
Docutils:</p>
<pre class="literal-block">
python setup.py install
</pre>
<div class="admonition caution">
<p class="first admonition-title">Caution!</p>
<p>This method is <strong>not</strong> recommended for day-to-day development;
it's too easy to forget. Confusion inevitably ensues.</p>
<p class="last">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.</p>
</div>
</li>
</ol>
<p>A useful addition to the <tt class="docutils literal">docutils</tt> top-level directory in branches
and alternate copies of the code is a <tt class="docutils literal"><span class="pre">set-PATHS</span></tt> file
containing the following lines:</p>
<pre class="literal-block">
# source this file
export PYTHONPATH=$PWD:$PWD/extras
export PATH=$PWD/tools:$PATH
</pre>
<p>Open a shell for this branch, <tt class="docutils literal">cd</tt> to the <tt class="docutils literal">docutils</tt> top-level
directory, and "source" this file. For example, using the bash
shell:</p>
<pre class="literal-block">
$ cd some-branch/docutils
$ . set-PATHS
</pre>
</div>
<div class="section" id="mailing-lists">
<h1><a class="toc-backref" href="#id15">Mailing Lists</a></h1>
<p>Developers are recommended to subscribe to all <a class="reference external" href="../user/mailing-lists.html">Docutils mailing
lists</a>.</p>
</div>
<div class="section" id="the-wiki">
<h1><a class="toc-backref" href="#id16">The Wiki</a></h1>
<p>There is a development wiki at <a class="reference external" href="http://docutils.python-hosting.com/">http://docutils.python-hosting.com/</a> as
a scratchpad for transient notes. Please use the repository for
permament document storage.</p>
</div>
<div class="section" id="extensions-and-related-projects">
<h1><a class="toc-backref" href="#id17">Extensions and Related Projects</a></h1>
<div class="section" id="the-sandbox">
<h2><a class="toc-backref" href="#id18">The Sandbox</a></h2>
<p>The <a class="reference external" href="http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/">sandbox directory</a> 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 Docutils
core. A project-specific subdirectory should be created for each new
project. Any developer who wants to play in the sandbox may do so,
but project directories are recommended over personal directories,
which discourage collaboration. It's OK to make a mess in the
sandbox! But please, play nice.</p>
<p>Please update the <a class="reference external" href="http://docutils.sf.net/sandbox/README.html">sandbox README</a> file with links and a brief
description of your work.</p>
<p>In order to minimize the work necessary for others to install and try
out new, experimental components, the following sandbox directory
structure is recommended:</p>
<pre class="literal-block">
sandbox/
project_name/ # For a collaborative project.
README.txt # Describe the requirements, purpose/goals, usage,
# and list the maintainers.
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.
userid/ # For *temporary* personal space.
</pre>
<p>Some sandbox projects are destined to move to the Docutils core once
completed. Others, such as add-ons to Docutils or applications of
Docutils, may graduate to become <a class="reference internal" href="#parallel-projects">parallel projects</a>.</p>
</div>
<div class="section" id="parallel-projects">
<span id="parallel-project"></span><h2><a class="toc-backref" href="#id19">Parallel Projects</a></h2>
<p>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.</p>
<p>An official parallel project will have its own directory beside (or
parallel to) the main <tt class="docutils literal">docutils</tt> 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.</p>
<p>A parallel project requires a project leader, who must commit to
coordinate and maintain the implementation:</p>
<ul class="simple">
<li>Answer questions from users and developers.</li>
<li>Review suggestions, bug reports, and patches.</li>
<li>Monitor changes and ensure the quality of the code and
documentation.</li>
<li>Coordinate with Docutils to ensure interoperability.</li>
<li>Put together official project releases.</li>
</ul>
<p>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.</p>
</div>
<div class="section" id="other-related-projects">
<h2><a class="toc-backref" href="#id20">Other related projects</a></h2>
<p>Many related but independent projects are listed in the Docutils
<a class="reference external" href="http://docutils.sourceforge.net/docs/user/links.html">link list</a>. If you want your project to appear there, drop a note at
the <a class="reference external" href="../user/mailing-lists.html#docutils-develop">Docutils-develop</a> mailing list.</p>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
</div>
</body>
</html>
|