source: html/ceps/cep-0001.html @ 2530

Last change on this file since 2530 was 2530, checked in by wehart, 9 years ago

CEP html updates

File size: 33.4 KB
Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<!--
5This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
6PEP, see http://www.python.org/dev/peps/pep-0001 for instructions and links
7to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8-->
9<head>
10  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11  <meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
12  <title>PEP 1 -- CEP Purpose and Guidelines</title>
13  <style type="text/css">
14
15/*
16:Author: David Goodger
17:Contact: goodger@python.org
18:date: $Date: 2006-05-21 14:44:42 -0600 (Sun, 21 May 2006) $
19:version: $Revision: 4564 $
20:copyright: This stylesheet has been placed in the public domain.
21
22Default cascading style sheet for the PEP HTML output of Docutils.
23*/
24
25/* "! important" is used here to override other ``margin-top`` and
26   ``margin-bottom`` styles that are later in the stylesheet or
27   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
28.first {
29  margin-top: 0 ! important }
30
31.last, .with-subtitle {
32  margin-bottom: 0 ! important }
33
34.hidden {
35  display: none }
36
37.navigation {
38  width: 100% ;
39  background: #99ccff ;
40  margin-top: 0px ;
41  margin-bottom: 0px }
42
43.navigation .navicon {
44  width: 150px ;
45  height: 35px }
46
47.navigation .textlinks {
48  padding-left: 1em ;
49  text-align: left }
50
51.navigation td, .navigation th {
52  padding-left: 0em ;
53  padding-right: 0em ;
54  vertical-align: middle }
55
56.rfc2822 {
57  margin-top: 0.5em ;
58  margin-left: 0.5em ;
59  margin-right: 0.5em ;
60  margin-bottom: 0em }
61
62.rfc2822 td {
63  text-align: left }
64
65.rfc2822 th.field-name {
66  text-align: right ;
67  font-family: sans-serif ;
68  padding-right: 0.5em ;
69  font-weight: bold ;
70  margin-bottom: 0em }
71
72a.toc-backref {
73  text-decoration: none ;
74  color: black }
75
76blockquote.epigraph {
77  margin: 2em 5em ; }
78
79body {
80  margin: 0px ;
81  margin-bottom: 1em ;
82  padding: 0px }
83
84dl.docutils dd {
85  margin-bottom: 0.5em }
86
87div.section {
88  margin-left: 1em ;
89  margin-right: 1em ;
90  margin-bottom: 1.5em }
91
92div.section div.section {
93  margin-left: 0em ;
94  margin-right: 0em ;
95  margin-top: 1.5em }
96
97div.abstract {
98  margin: 2em 5em }
99
100div.abstract p.topic-title {
101  font-weight: bold ;
102  text-align: center }
103
104div.admonition, div.attention, div.caution, div.danger, div.error,
105div.hint, div.important, div.note, div.tip, div.warning {
106  margin: 2em ;
107  border: medium outset ;
108  padding: 1em }
109
110div.admonition p.admonition-title, div.hint p.admonition-title,
111div.important p.admonition-title, div.note p.admonition-title,
112div.tip p.admonition-title {
113  font-weight: bold ;
114  font-family: sans-serif }
115
116div.attention p.admonition-title, div.caution p.admonition-title,
117div.danger p.admonition-title, div.error p.admonition-title,
118div.warning p.admonition-title {
119  color: red ;
120  font-weight: bold ;
121  font-family: sans-serif }
122
123/* Uncomment (and remove this text!) to get reduced vertical space in
124   compound paragraphs.
125div.compound .compound-first, div.compound .compound-middle {
126  margin-bottom: 0.5em }
127
128div.compound .compound-last, div.compound .compound-middle {
129  margin-top: 0.5em }
130*/
131
132div.dedication {
133  margin: 2em 5em ;
134  text-align: center ;
135  font-style: italic }
136
137div.dedication p.topic-title {
138  font-weight: bold ;
139  font-style: normal }
140
141div.figure {
142  margin-left: 2em ;
143  margin-right: 2em }
144
145div.footer, div.header {
146  clear: both;
147  font-size: smaller }
148
149div.footer {
150  margin-left: 1em ;
151  margin-right: 1em }
152
153div.line-block {
154  display: block ;
155  margin-top: 1em ;
156  margin-bottom: 1em }
157
158div.line-block div.line-block {
159  margin-top: 0 ;
160  margin-bottom: 0 ;
161  margin-left: 1.5em }
162
163div.sidebar {
164  margin-left: 1em ;
165  border: medium outset ;
166  padding: 1em ;
167  background-color: #ffffee ;
168  width: 40% ;
169  float: right ;
170  clear: right }
171
172div.sidebar p.rubric {
173  font-family: sans-serif ;
174  font-size: medium }
175
176div.system-messages {
177  margin: 5em }
178
179div.system-messages h1 {
180  color: red }
181
182div.system-message {
183  border: medium outset ;
184  padding: 1em }
185
186div.system-message p.system-message-title {
187  color: red ;
188  font-weight: bold }
189
190div.topic {
191  margin: 2em }
192
193h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
194h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
195  margin-top: 0.4em }
196
197h1 {
198  font-family: sans-serif ;
199  font-size: large }
200
201h2 {
202  font-family: sans-serif ;
203  font-size: medium }
204
205h3 {
206  font-family: sans-serif ;
207  font-size: small }
208
209h4 {
210  font-family: sans-serif ;
211  font-style: italic ;
212  font-size: small }
213
214h5 {
215  font-family: sans-serif;
216  font-size: x-small }
217
218h6 {
219  font-family: sans-serif;
220  font-style: italic ;
221  font-size: x-small }
222
223hr.docutils {
224  width: 75% }
225
226img.align-left {
227  clear: left }
228
229img.align-right {
230  clear: right }
231
232img.borderless {
233  border: 0 }
234
235ol.simple, ul.simple {
236  margin-bottom: 1em }
237
238ol.arabic {
239  list-style: decimal }
240
241ol.loweralpha {
242  list-style: lower-alpha }
243
244ol.upperalpha {
245  list-style: upper-alpha }
246
247ol.lowerroman {
248  list-style: lower-roman }
249
250ol.upperroman {
251  list-style: upper-roman }
252
253p.attribution {
254  text-align: right ;
255  margin-left: 50% }
256
257p.caption {
258  font-style: italic }
259
260p.credits {
261  font-style: italic ;
262  font-size: smaller }
263
264p.label {
265  white-space: nowrap }
266
267p.rubric {
268  font-weight: bold ;
269  font-size: larger ;
270  color: maroon ;
271  text-align: center }
272
273p.sidebar-title {
274  font-family: sans-serif ;
275  font-weight: bold ;
276  font-size: larger }
277
278p.sidebar-subtitle {
279  font-family: sans-serif ;
280  font-weight: bold }
281
282p.topic-title {
283  font-family: sans-serif ;
284  font-weight: bold }
285
286pre.address {
287  margin-bottom: 0 ;
288  margin-top: 0 ;
289  font-family: serif ;
290  font-size: 100% }
291
292pre.literal-block, pre.doctest-block {
293  margin-left: 2em ;
294  margin-right: 2em }
295
296span.classifier {
297  font-family: sans-serif ;
298  font-style: oblique }
299
300span.classifier-delimiter {
301  font-family: sans-serif ;
302  font-weight: bold }
303
304span.interpreted {
305  font-family: sans-serif }
306
307span.option {
308  white-space: nowrap }
309
310span.option-argument {
311  font-style: italic }
312
313span.pre {
314  white-space: pre }
315
316span.problematic {
317  color: red }
318
319span.section-subtitle {
320  /* font-size relative to parent (h1..h6 element) */
321  font-size: 80% }
322
323table.citation {
324  border-left: solid 1px gray;
325  margin-left: 1px }
326
327table.docinfo {
328  margin: 2em 4em }
329
330table.docutils {
331  margin-top: 0.5em ;
332  margin-bottom: 0.5em }
333
334table.footnote {
335  border-left: solid 1px black;
336  margin-left: 1px }
337
338table.docutils td, table.docutils th,
339table.docinfo td, table.docinfo th {
340  padding-left: 0.5em ;
341  padding-right: 0.5em ;
342  vertical-align: top }
343
344td.num {
345  text-align: right }
346
347th.field-name {
348  font-weight: bold ;
349  text-align: left ;
350  white-space: nowrap ;
351  padding-left: 0 }
352
353h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
354h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
355  font-size: 100% }
356
357ul.auto-toc {
358  list-style-type: none }
359
360</style>
361</head>
362<body bgcolor="white">
363<table class="navigation" cellpadding="0" cellspacing="0"
364       width="100%" border="0">
365<tr><td class="navicon" width="150" height="35">
366<a href="http://www.python.org/" title="Python Home Page">
367<img src="http://www.python.org/pics/PyBanner038.gif" alt="[Python]"
368 border="0" width="150" height="35" /></a></td>
369<td class="textlinks" align="left">
370[<b><a href="http://www.python.org/">Python Home</a></b>]
371[<b><a href="http://www.python.org/dev/peps/">PEP Index</a></b>]
372[<b><a href="./pep-0001.txt">PEP Source</a></b>]
373</td></tr></table>
374<div class="document">
375<table class="rfc2822 docutils field-list" frame="void" rules="none">
376<col class="field-name" />
377<col class="field-body" />
378<tbody valign="top">
379<tr class="field"><th class="field-name">CEP:</th><td class="field-body">1</td>
380</tr>
381<tr class="field"><th class="field-name">Title:</th><td class="field-body">CEP Purpose and Guidelines</td>
382</tr>
383<tr class="field"><th class="field-name">Version:</th><td class="field-body">78677</td>
384</tr>
385<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://svn.python.org/view/*checkout*/peps/trunk/pep-0001.txt">2010-03-04 20:07:12 -0700 (Thu, 04 Mar 2010)</a></td>
386</tr>
387<tr class="field"><th class="field-name">Author:</th><td class="field-body">William Hart</td>
388</tr>
389<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
390</tr>
391<tr class="field"><th class="field-name">Type:</th><td class="field-body">Process</td>
392</tr>
393<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="http://www.python.org/dev/peps/pep-0012">text/x-rst</a></td>
394</tr>
395<tr class="field"><th class="field-name">Created:</th><td class="field-body">09-Apr-2010</td>
396</tr>
397<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
398</tr>
399</tbody>
400</table>
401<hr />
402<div class="contents topic" id="contents">
403<p class="topic-title first">Contents</p>
404<ul class="simple">
405<li><a class="reference internal" href="#what-is-a-cep" id="id18">What is a CEP?</a></li>
406<li><a class="reference internal" href="#cep-types" id="id19">CEP Types</a></li>
407<li><a class="reference internal" href="#cep-work-flow" id="id20">CEP Work Flow</a></li>
408<li><a class="reference internal" href="#what-belongs-in-a-successful-cep" id="id21">What belongs in a successful CEP?</a></li>
409<li><a class="reference internal" href="#cep-formats-and-templates" id="id22">CEP Formats and Templates</a></li>
410<li><a class="reference internal" href="#cep-header-preamble" id="id23">CEP Header Preamble</a></li>
411<li><a class="reference internal" href="#auxiliary-files" id="id24">Auxiliary Files</a></li>
412<li><a class="reference internal" href="#reporting-cep-bugs-or-submitting-cep-updates" id="id25">Reporting CEP Bugs, or Submitting CEP Updates</a></li>
413<li><a class="reference internal" href="#transferring-cep-ownership" id="id26">Transferring CEP Ownership</a></li>
414<li><a class="reference internal" href="#cep-editor-responsibilities-workflow" id="id27">CEP Editor Responsibilities &amp; Workflow</a></li>
415<li><a class="reference internal" href="#references-and-footnotes" id="id28">References and Footnotes</a></li>
416<li><a class="reference internal" href="#copyright" id="id29">Copyright</a></li>
417</ul>
418</div>
419<div class="section" id="what-is-a-cep">
420<h1><a class="toc-backref" href="#id18">What is a CEP?</a></h1>
421<p>CEP stands for Coopr Enhancement Proposal.  A CEP is a design
422document providing information to the Coopr community, or describing
423a new feature for Coopr or its processes or environment.  The CEP
424should provide a concise technical specification of the feature and a
425rationale for the feature.</p>
426<p>We intend CEPs to be the primary mechanisms for proposing new
427features, for collecting community input on an issue, and for
428documenting the design decisions that have gone into Coopr.  The CEP
429author is responsible for building consensus within the community and
430documenting dissenting opinions.</p>
431<p>Because the CEPs are maintained as text files in a versioned
432repository, their revision history is the historical record of the
433feature proposal <a class="footnote-reference" href="#id7" id="id1">[1]</a>.</p>
434</div>
435<div class="section" id="cep-types">
436<h1><a class="toc-backref" href="#id19">CEP Types</a></h1>
437<p>There are three kinds of CEP:</p>
438<ol class="arabic simple">
439<li>A <strong>Standards Track</strong> CEP describes a new feature or implementation
440for Coopr packages.</li>
441<li>An <strong>Informational</strong> CEP describes a Coopr design issue, or
442provides general guidelines or information to the Coopr community,
443but does not propose a new feature.  Informational CEPs do not
444necessarily represent a Coopr community consensus or
445recommendation, so users and implementors are free to ignore
446Informational CEPs or follow their advice.</li>
447<li>A <strong>Process</strong> CEP describes a process surrounding Coopr, or
448proposes a change to (or an event in) a process.  Process CEPs are
449like Standards Track CEPs but apply to areas other than Coopr
450packages.  They may propose an implementation, but not to
451Coopr's codebase; they often require community consensus; unlike
452Informational CEPs, they are more than recommendations, and users
453are typically not free to ignore them.  Examples include
454procedures, guidelines, changes to the decision-making process, and
455changes to the tools or environment used in Coopr development.
456Any meta-CEP is also considered a Process CEP.</li>
457</ol>
458</div>
459<div class="section" id="cep-work-flow">
460<h1><a class="toc-backref" href="#id20">CEP Work Flow</a></h1>
461<p>The CEP process begins with a new idea for Coopr.  The CEP editors assign
462CEP numbers and change their status.  Please send all CEP-related email
463to &lt;<a class="reference external" href="mailto:coopr-developers&#64;googlegroups.com">coopr-developers&#64;googlegroups.com</a>&gt; with a subject starting with <cite>CEP</cite>.</p>
464<p>It is highly recommended that a single CEP contain a single key proposal
465or new idea. Small enhancements or patches often do not need a CEP; a
466patch submission can be submitted as a Coopr ticket.  A more focussed
467CEP will likely be more successful, and the CEP editor may reject CEP
468proposals that are not focused or too broad.  If in doubt, split your
469CEP into several well-focussed ones.</p>
470<p>Each CEP must have a champion -- someone who writes the CEP using
471the style and format described below, shepherds the discussions in the
472appropriate forums, and attempts to build community consensus around the
473idea.  The CEP champion (a.k.a. Author) should first attempt to ascertain
474whether the idea is CEP-able.  For example, discussing the CEP on the
475&lt;<a class="reference external" href="mailto:coopr-developers&#64;googlegroups.com">coopr-developers&#64;googlegroups.com</a>&gt; or &lt;<a class="reference external" href="mailto:coopr-forum&#64;googlegroups.com">coopr-forum&#64;googlegroups.com</a>&gt;
476can help evaluate whther the idea might be rejected due to issues that
477are well-known by Coopr developers.</p>
478<p>The CEP editor that approves a CEP will assign it a CEP a number,
479label it as Standards Track, Informational, or Process, give it
480status &quot;Draft&quot;, and create and check-in the initial draft of the CEP.
481The CEP editor will not unreasonably deny a CEP.  Reasons for denying
482CEP status include duplication of effort, being technically unsound,
483not providing proper motivation or addressing backwards compatibility,
484or not in keeping with Coopr's design philosophy.</p>
485<p>As updates are necessary, the CEP author can check in new versions if
486they have SVN commit permissions, or can email new CEP versions to the
487CEP editor for committing.</p>
488<p>Standards Track CEPs consist of two parts, a design document and a
489reference implementation.  The CEP should be reviewed and accepted before
490a reference implementation is begun, unless a reference implementation
491will aid people in studying the CEP.  Standards Track CEPs must include
492an implementation -- in the form of code, a patch, or a URL to same --
493before it can be considered Final.</p>
494<p>Once the authors have completed a CEP, they must inform the CEP editor
495that it is ready for review.  CEPs are reviewed the Coopr project leader,
496and other individuals identified by the editor.  The reviewers may accept
497or reject a CEP or send it back to the author(s) for revision.  For a CEP
498to be accepted it must meet certain minimum criteria.  It must be a clear
499and complete description of the proposed enhancement.  The enhancement
500must represent a net improvement.  The proposed implementation,
501if applicable, must be solid and must not complicate core Coopr
502functionality unduly.  Finally, a proposed enhancement must be match
503the design philosophy of Coopr, or provide a clear justification for why
504this design departure is acceptable.</p>
505<p>Once a CEP has been accepted, the reference implementation must be
506completed.  When the reference implementation is complete and accepted,
507the status will be changed to &quot;Final&quot;.</p>
508<p>A CEP can also be assigned status &quot;Deferred&quot;.  The CEP author or editor
509can assign the CEP this status when no progress is being made on the CEP.
510Once a CEP is deferred, the CEP editor can re-assign it to draft status.</p>
511<p>A CEP can also be &quot;Rejected&quot;.  Perhaps after all is said and done it
512was not a good idea.  It is still important to have a record of this fact.</p>
513<p>CEPs can also be replaced by a different CEP, rendering the original
514obsolete.  This is intended for Informational CEPs, where version 2 of
515an API can replace version 1.</p>
516<p>Some Informational and Process CEPs may also have a status of &quot;Active&quot;
517if they are never meant to be completed.  E.g. CEP 1 (this CEP).</p>
518</div>
519<div class="section" id="what-belongs-in-a-successful-cep">
520<h1><a class="toc-backref" href="#id21">What belongs in a successful CEP?</a></h1>
521<p>Each CEP should have the following parts:</p>
522<ol class="arabic">
523<li><p class="first">Preamble -- <a class="reference external" href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> style headers containing meta-data about the
524CEP, including the CEP number, a short descriptive title (limited
525to a maximum of 44 characters), the names, and optionally the
526contact info for each author, etc.</p>
527</li>
528<li><p class="first">Abstract -- a short (~200 word) description of the technical issue
529being addressed.</p>
530</li>
531<li><p class="first">Copyright/public domain -- Each CEP must either be explicitly
532labelled as placed in the public domain (see this CEP as an
533example) or licensed under the <a class="reference external" href="http://www.opencontent.org/openpub/">Open Publication License</a> <a class="footnote-reference" href="#id11" id="id12">[5]</a>.</p>
534</li>
535<li><p class="first">Specification -- The technical specification should describe the
536syntax and semantics of any new language feature.  The specification
537should be detailed enough to allow competing, interoperable
538implementations for any of the current Python platforms.</p>
539</li>
540<li><p class="first">Motivation -- The motivation is critical for CEPs that want to
541change core Coopr functionality.  It should clearly explain why
542existing Coopr functionality is inadequate to address the problem
543that the CEP solves.  CEP submissions without sufficient motivation
544may be rejected outright.</p>
545</li>
546<li><p class="first">Rationale -- The rationale fleshes out the specification by
547describing what motivated the design and why particular design
548decisions were made.  It should describe alternate designs that
549were considered and related work, e.g. how the feature is supported
550in similar software packages (e.g. PuLP or AMPL).</p>
551<p>The rationale should provide evidence of consensus within the
552community and discuss important objections or concerns raised
553during discussion.</p>
554</li>
555<li><p class="first">Backwards Compatibility -- All CEPs that introduce backwards
556incompatibilities must include a section describing these
557incompatibilities and their severity.  The CEP must explain how the
558author proposes to deal with these incompatibilities.  CEP
559submissions without a sufficient backwards compatibility treatise
560may be rejected outright.</p>
561</li>
562<li><p class="first">Reference Implementation -- The reference implementation must be
563completed before any CEP is given status &quot;Final&quot;, but it need not
564be completed before the CEP is accepted.  It is better to finish
565the specification and rationale first and reach consensus on it
566before writing code.</p>
567<p>The final implementation must include test code and documentation
568appropriate for either the Coopr reference manual.</p>
569</li>
570</ol>
571</div>
572<div class="section" id="cep-formats-and-templates">
573<h1><a class="toc-backref" href="#id22">CEP Formats and Templates</a></h1>
574<p>There are two CEP formats available to authors: plaintext and
575<a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> <a class="footnote-reference" href="#id13" id="id14">[6]</a>.  Both are UTF-8-encoded text files.</p>
576<p>Plaintext CEPs are written with minimal structural markup that adheres
577to a rigid style.  CEP 3 contains a instructions and a template <a class="footnote-reference" href="#id8" id="id2">[2]</a>
578you can use to get started writing your plaintext CEP.</p>
579<p><a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReStructuredText</a> <a class="footnote-reference" href="#id13" id="id15">[6]</a> CEPs allow for rich markup that is still quite easy
580to read, but results in much better-looking and more functional HTML.
581CEP 3 contains instructions and a template <a class="footnote-reference" href="#id9" id="id3">[3]</a> for reStructuredText
582CEPs.</p>
583<p>There is a Python script that converts both styles of CEPs to HTML for
584viewing on the web <a class="footnote-reference" href="#id10" id="id4">[4]</a>.  Parsing and conversion of plaintext CEPs is
585self-contained within the script.  reStructuredText CEPs are parsed
586and converted by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> <a class="footnote-reference" href="#id16" id="id17">[7]</a> code called from the script.</p>
587</div>
588<div class="section" id="cep-header-preamble">
589<h1><a class="toc-backref" href="#id23">CEP Header Preamble</a></h1>
590<p>Each CEP must begin with an <a class="reference external" href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> style header preamble.  The headers
591must appear in the following order.  Headers marked with &quot;*&quot; are
592optional and are described below.  All other headers are required.</p>
593<pre class="literal-block">
594  CEP: &lt;cep number&gt;
595  Title: &lt;cep title&gt;
596  Version: &lt;svn version string&gt;
597  Last-Modified: &lt;svn date string&gt;
598  Author: &lt;list of authors' real names and optionally, email addrs&gt;
599* Discussions-To: &lt;email address&gt;
600  Status: &lt;Draft | Active | Accepted | Deferred | Rejected |
601           Withdrawn | Final | Replaced&gt;
602  Type: &lt;Standards Track | Informational | Process&gt;
603* Content-Type: &lt;text/plain | text/x-rst&gt;
604* Requires: &lt;cep numbers&gt;
605  Created: &lt;date created on, in dd-mmm-yyyy format&gt;
606* Coopr-Version: &lt;version number&gt;
607  Post-History: &lt;dates of postings to coopr-forum or coopr-developers&gt;
608* Replaces: &lt;cep number&gt;
609* Replaced-By: &lt;cep number&gt;
610</pre>
611<p>The Author header lists the names, and optionally the email addresses
612of all the authors/owners of the CEP.  The format of the Author header
613value must be</p>
614<blockquote>
615Random J. User &lt;<a class="reference external" href="mailto:address&#64;dom.ain">address&#64;dom.ain</a>&gt;</blockquote>
616<p>if the email address is included, and just</p>
617<blockquote>
618Random J. User</blockquote>
619<p>if the address is not given.  If there are multiple authors, each should
620be on a separate line following <a class="reference external" href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> continuation line conventions.
621Note that personal email addresses in CEPs will be obscured as a defense
622against spam harvesters.</p>
623<p>While a CEP is in private discussions (usually during the initial
624Draft phase), a Discussions-To header will indicate the mailing list
625or URL where the CEP is being discussed.  No Discussions-To header is
626necessary if the CEP is being discussed privately with the author, or
627on the coopr-forum or coopr-developers email mailing lists.  Note that
628email addresses in the Discussions-To header will not be obscured.</p>
629<p>The Type header specifies the type of CEP: Standards Track,
630Informational, or Process.</p>
631<p>The format of a CEP is specified with a Content-Type header.  The
632acceptable values are &quot;text/plain&quot; for plaintext CEPs (see CEP 3 <a class="footnote-reference" href="#id8" id="id5">[2]</a>)
633and &quot;text/x-rst&quot; for reStructuredText CEPs (see CEP 3 <a class="footnote-reference" href="#id9" id="id6">[3]</a>).
634Plaintext (&quot;text/plain&quot;) is the default if no Content-Type header is
635present.</p>
636<p>The Created header records the date that the CEP was assigned a
637number, while Post-History is used to record the dates of when new
638versions of the CEP are posted to coopr-forum and/or coopr-developers.  Both
639headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.</p>
640<p>Standards Track CEPs must have a Coopr-Version header which indicates
641the version of Coopr that the feature will be released with.
642Informational and Process CEPs do not need a Coopr-Version header.</p>
643<p>CEPs may have a Requires header, indicating the CEP numbers that this
644CEP depends on.</p>
645<p>CEPs may also have a Replaced-By header indicating that a CEP has been
646rendered obsolete by a later document; the value is the number of the
647CEP that replaces the current document.  The newer CEP must have a
648Replaces header containing the number of the CEP that it rendered
649obsolete.</p>
650</div>
651<div class="section" id="auxiliary-files">
652<h1><a class="toc-backref" href="#id24">Auxiliary Files</a></h1>
653<p>CEPs may include auxiliary files such as diagrams.  Such files must be
654named <tt class="docutils literal"><span class="pre">cep-XXXX-Y.ext</span></tt>, where &quot;XXXX&quot; is the CEP number, &quot;Y&quot; is a
655serial number (starting at 1), and &quot;ext&quot; is replaced by the actual
656file extension (e.g. &quot;png&quot;).</p>
657</div>
658<div class="section" id="reporting-cep-bugs-or-submitting-cep-updates">
659<h1><a class="toc-backref" href="#id25">Reporting CEP Bugs, or Submitting CEP Updates</a></h1>
660<p>How you report a bug, or submit a CEP update depends on several factors,
661such as the maturity of the CEP, the preferences of the CEP author, and
662the nature of your comments.  For the early draft stages of the CEP,
663it is probably best to send your comments and changes directly to the
664CEP author.  For more mature, or finished CEPs you may want to submit
665corrections as Coopr tickets so that your changes do not get lost.
666If the CEP author is a Coopr developer, assign the bug/patch to him,
667otherwise assign it to the CEP editor.</p>
668<p>When in doubt about where to send your changes, please check first with
669the CEP author and/or CEP editor.</p>
670<p>CEP authors who are also Coopr developers can update the
671CEPs themselves by using &quot;svn commit&quot; to commit their changes.</p>
672</div>
673<div class="section" id="transferring-cep-ownership">
674<h1><a class="toc-backref" href="#id26">Transferring CEP Ownership</a></h1>
675<p>It occasionally becomes necessary to transfer ownership of CEPs to
676a new champion.  In general, we would like to retain the original
677author as a co-author of the transferred CEP, but that is really up to
678the original author.  For example, it may be necessary to to transfer
679ownership  of a CEP when the original author no longer has the time or
680interest in updating it or following through with the CEP process.</p>
681<p>If you are interested in assuming ownership of a CEP, send a message
682asking to take over, addressed to both the original author and the CEP
683editor.  If the original author does not respond to email in a timely
684manner, the CEP editor will make a unilateral decision.</p>
685</div>
686<div class="section" id="cep-editor-responsibilities-workflow">
687<h1><a class="toc-backref" href="#id27">CEP Editor Responsibilities &amp; Workflow</a></h1>
688<p>The role of the CEP editor is to manage the administrative and editorial
689part aspects of managing CEPs.  Currently, the CEP editor also has the
690final say in the acceptance of CEPs.  (Note:  This differs from Python's
691model of using a benevalent dictator for life (BDFL), which is not the
692CEP editor.  If the CEP editor responsibilities become significant,
693then we could envision this separate role within Coopr.  But for now
694the CEP editor also serves as the Coopr BDFL.)</p>
695<p>The CEP editor must subscribe to the &lt;<a class="reference external" href="mailto:coopr-admin&#64;googlegroups.org">coopr-admin&#64;googlegroups.org</a>&gt;
696list.  All CEP-related correspondence should be sent (or CC'd) to
697&lt;<a class="reference external" href="mailto:coopr-admin&#64;googlegroups.com">coopr-admin&#64;googlegroups.com</a>&gt;.  For each new CEP that comes in the editor
698does the following:</p>
699<ul class="simple">
700<li>Read the CEP to check if it is ready: sound and complete.  The ideas
701must make technical sense, even if they don't seem likely to be
702accepted.</li>
703<li>The title should accurately describe the content.</li>
704<li>Edit the CEP for language (spelling, grammar, sentence structure,
705etc.), markup (for reST CEPs), code style (examples should match CEP
7068 &amp; 7).</li>
707</ul>
708<p>If the CEP is not ready, the editor will send it back to the author for
709revision, with specific instructions.</p>
710<p>Once the CEP is ready for the repository, the CEP editor will:</p>
711<ul>
712<li><p class="first">Assign a CEP number</p>
713</li>
714<li><p class="first">List the CEP in CEP 0 (in two places: the categorized list, and the
715numeric list).</p>
716</li>
717<li><p class="first">Add the CEP to SVN.</p>
718<p>The command to check out and edit the repository is:</p>
719<pre class="literal-block">
720svn checkout https://software.sandia.gov/svn/public/coopr/trunk/ceps
721</pre>
722<p>In particular, the <tt class="docutils literal"><span class="pre">svn:eol-style</span></tt> property should be set to <tt class="docutils literal">native</tt>
723and the <tt class="docutils literal">svn:keywords</tt> property to <tt class="docutils literal">Author Date Id Revision</tt>.</p>
724<p>Also, the 'make' command needs to be run to generate new CEP web pages,
725which need to be added to the repository.</p>
726</li>
727<li><p class="first">Send email back to the CEP author with next steps (post to
728coopr-forum and coopr-developers).</p>
729</li>
730</ul>
731<p>Updates to existing CEPs also come in to &lt;<a class="reference external" href="mailto:coopr-admin&#64;googlegroups.org">coopr-admin&#64;googlegroups.org</a>&gt;.
732Many CEP authors are not SVN committers yet, so we do the commits
733for them.</p>
734<p>Many CEPs are written and maintained by developers with write access
735to the Coopr codebase.  The CEP editor monitors Coopr checkins for CEP
736changes, and correct any structure, grammar, spelling, or markup mistakes.</p>
737</div>
738<div class="section" id="references-and-footnotes">
739<h1><a class="toc-backref" href="#id28">References and Footnotes</a></h1>
740<table class="docutils footnote" frame="void" id="id7" rules="none">
741<colgroup><col class="label" /><col /></colgroup>
742<tbody valign="top">
743<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This historical record is available by the normal SVN commands
744for retrieving older revisions.  For those without direct access to
745the SVN tree, you can browse the current and past CEP revisions here:
746<a class="reference external" href="https://projects.coin-or.org/Coopr/browser/ceps">https://projects.coin-or.org/Coopr/browser/ceps</a></td></tr>
747</tbody>
748</table>
749<table class="docutils footnote" frame="void" id="id8" rules="none">
750<colgroup><col class="label" /><col /></colgroup>
751<tbody valign="top">
752<tr><td class="label">[2]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id5">2</a>)</em> CEP 2, Sample Plaintext CEP Template
753(<a class="reference external" href="http://www.coin-or.org/Coopr/ceps/cep-0002.html">http://www.coin-or.org/Coopr/ceps/cep-0002.html</a>)</td></tr>
754</tbody>
755</table>
756<table class="docutils footnote" frame="void" id="id9" rules="none">
757<colgroup><col class="label" /><col /></colgroup>
758<tbody valign="top">
759<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id6">2</a>)</em> CEP 3, Sample reStructuredText CEP Template
760(<a class="reference external" href="http://www.coin-or.org/Coopr/ceps/cep-0003.html">http://www.coin-or.org/Coopr/ceps/cep-0003.html</a>)</td></tr>
761</tbody>
762</table>
763<table class="docutils footnote" frame="void" id="id10" rules="none">
764<colgroup><col class="label" /><col /></colgroup>
765<tbody valign="top">
766<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>The script referred to here is cep2pyramid.py, the successor to
767cep2html.py.  The URL for viewing CEPs on the web is
768<a class="reference external" href="http://www.coin-or.org/Coopr/ceps/">http://www.coin-or.org/Coopr/ceps/</a>.</td></tr>
769</tbody>
770</table>
771<table class="docutils footnote" frame="void" id="id11" rules="none">
772<colgroup><col class="label" /><col /></colgroup>
773<tbody valign="top">
774<tr><td class="label"><a class="fn-backref" href="#id12">[5]</a></td><td><a class="reference external" href="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</a></td></tr>
775</tbody>
776</table>
777<table class="docutils footnote" frame="void" id="id13" rules="none">
778<colgroup><col class="label" /><col /></colgroup>
779<tbody valign="top">
780<tr><td class="label">[6]</td><td><em>(<a class="fn-backref" href="#id14">1</a>, <a class="fn-backref" href="#id15">2</a>)</em> <a class="reference external" href="http://docutils.sourceforge.net/rst.html">http://docutils.sourceforge.net/rst.html</a></td></tr>
781</tbody>
782</table>
783<table class="docutils footnote" frame="void" id="id16" rules="none">
784<colgroup><col class="label" /><col /></colgroup>
785<tbody valign="top">
786<tr><td class="label"><a class="fn-backref" href="#id17">[7]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr>
787</tbody>
788</table>
789</div>
790<div class="section" id="copyright">
791<h1><a class="toc-backref" href="#id29">Copyright</a></h1>
792<p>Copyright 2010 by Sandia National Laboratories.  Sandia National
793Laboratories is a multi-program laboratory operated by Sandia
794Corporation, a wholly owned subsidiary of Lockheed Martin company, for
795the U.S. Department of Energy's National Nuclear Security Administration
796under contract DE-AC04-94AL85000.</p>
797<!-- Local Variables:
798mode: indented-text
799indent-tabs-mode: nil
800sentence-end-double-space: t
801fill-column: 70
802coding: utf-8
803End: -->
804</div>
805
806</div>
807</body>
808</html>
Note: See TracBrowser for help on using the repository browser.