Page "PageTemplates/Proposals" was changed by olemis Diff URL: <https://issues.apache.org/bloodhound/wiki/PageTemplates/Proposals?action=diff&version=2> Revision 2 Comment: WikiFormatting BEP template Changes: -------8<------8<------8<------8<------8<------8<------8<------8<-------- Index: PageTemplates/Proposals ========================================================================= --- PageTemplates/Proposals (version: 1) +++ PageTemplates/Proposals (version: 2) @@ -1,155 +1,78 @@ -|| '''PEP''' || 9 || -|| '''Title''' || Sample Plaintext PEP Template || -|| '''Version''' || [http://hg.python.org/peps/file/27140e5612b9/pep-0009.txt 27140e5612b9] || -|| '''Last-Modified''' || [http://hg.python.org/peps/file/tip/pep-0001.txt 2008-08-10 17:25:11 +0000 (Sun, 10 Aug 2008)] || -|| '''Author''' || Barry Warsaw <barry at python.org> || -|| '''Status''' || Active || -|| '''Type''' || Process || -|| '''Content-Type''' || [http://www.python.org/dev/peps/pep-0001/ text/plain] || -|| '''Created''' || 14-Aug-2001 || -|| '''Post-History''' || || += BEP <BEP number> : <BEP title> #overview + +[[PageOutline]] + +|| '''PEP''' || <BEP number> || +|| '''Title''' || <BEP title> || +|| '''Version''' || <leave blank> || +|| '''Last-Modified''' || <leave blank> || +|| '''Author''' || Author With Email <[email protected]>, Author Name Only, or The Bloodhound project (see [wiki:/Proposals#bep-header-preamble BEP preamble explained]) || +|| '''Status''' || Draft || +|| '''Type''' || <BEP type (see [wiki:/Proposals#bep-types BEP types explained])> || +|| '''Content-Type''' || [wiki:PageTemplates/Proposals text/x-trac-wiki] || +|| '''Created''' || <leave blank> || +|| '''Post-History''' || <leave blank> || ---- -== Abstract == +== Abstract #abstract -This ''PEP'' provides a boilerplate or sample template for creating your own plaintext PEPs. In conjunction with the content guidelines in [http://www.python.org/dev/peps/pep-0001/ PEP 1] , this should make it easy for you to conform your own PEPs to the format outlined below. +<Delete text in this section and add a short (~200 word) description of the technical issue being addressed. Take a look at sample abstract below> -'''Note:''' if you are reading this ''PEP'' via the web, you should first grab the plaintext source of this ''PEP'' in order to complete the steps below. DO NOT USE THE HTML FILE AS YOUR TEMPLATE! +This template provides a boilerplate or sample template for creating your +own BEPs. In conjunction with the [wiki:/Proposals general content guidelines] and the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] +, this should make it easy for you to conform your own +BEPs to the format outlined below. See [#howto How to Use This Template] for further instructions. -To get the source this (or any) ''PEP'', look at the top of the HTML page and click on the date & time on the '''Last-Modified''' line. It is a link to the source text in the Python repository. +**Note**: if you are reading this template via the web, you should first try to create a new wiki page by selecting `ProposalsRst` |page template guide|. **DO NOT EDIT THIS WIKI PAGE IN ORDER TO CREATE A NEW BEP! ** -If you would prefer to use lightweight markup in your ''PEP'', please see [http://www.python.org/dev/peps/pep-0012/ PEP 12], ''"Sample reStructuredText ''PEP'' Template"'' . +If you would prefer not to use WikiFormatting markup in your BEP, please see [wiki:/Proposals/Formats/RestructuredText reStructuredText BEP guidelines]. -== Rationale == +== Proposal #proposal -''PEP'' submissions come in a wide variety of forms, not all adhering to the format guidelines set forth below. Use this template, in conjunction with the content guidelines in [http://www.python.org/dev/peps/pep-0001/ PEP 1], to ensure that your ''PEP'' submission won't get automatically rejected because of form. +<The technical specification should describe any new features , detail its impact on the components architecture , mention what plugins will be included as a result , whether they are hosted by [http://trac-hacks.org trac-hacks.org] or not , and any other relevant technical subject . The specification should be detailed enough to allow competing, interoperable implementations for any of the current supported database platforms (e.g. ''SQLite'', ''Postgres'', ''MySQL'') and server technologies (e.g. ''Apache HTTPD server'', ''nginx'', ''mod_wsgi'', ''CGI'').. > +== Rationale #rationale -== How to Use This Template == +<The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other issue trackers or ''Trac'' hacks . The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion. Take a look at sample rationale below> -To use this template you must first decide whether your ''PEP'' is going to be an ''Informational'' or ''Standards Track'' PEP. Most PEPs are ''Standards Track'' because they propose a new feature for the [http://www.python.org Python] language or standard library. When in doubt, read [http://www.python.org/dev/peps/pep-0001/ PEP 1] for details or contact the ''PEP'' editors <[email protected]>. +''BEP'' submissions come in a wide variety of forms, not all adhering to the format guidelines set forth below. Use this template, in conjunction with the [wiki:/Proposals general content guidelines] and the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines], to ensure that your ''BEP'' submission is easy to read and understand. -Once you've decided which type of ''PEP'' yours is going to be, follow the directions below. +This template allows to create BEPs and is very similar to [http://www.python.org/dev/peps/pep-0012 PEP 12] . However it has been optimized by moving long explanations to the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] . If you are interested take a look at the [?action=diff&old_version=1 differences]. The goal is to redact new BEPs just by following in-line instructions between angle brackets (i.e. **<** **>**) . Even if this will allow to write BEPs faster , it is highly recommended to read the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] at least once in your lifetime to be aware of good practices and expected style rules . - - Make a copy of this file (.txt file, not HTML!) and perform the - following edits. - - Replace the "PEP: 9" header with "PEP: XXX" since you don't yet - have a ''PEP'' number assignment. - - Change the '''Title''' header to the title of your PEP. - - Leave the '''Version''' and '''Last-Modified''' headers alone; we'll take - care of those when we check your ''PEP'' into Python's Subversion - repository. These headers consist of keywords ("Revision" and - "Date" enclosed in "$"-signs) which are automatically expanded - by the repository. Please do not edit the expanded date or - revision text. - - Change the '''Author''' header to include your name, and optionally - your email address. Be sure to follow the format carefully: - your name must appear first, and it must not be contained in - parentheses. Your email address may appear second (or it can be - omitted) and if it appears, it must appear in angle brackets. - It is okay to obfuscate your email address. - - If there is a mailing list for discussion of your new feature, - add a '''Discussions-To''' header right after the '''Author''' header. You - should not add a '''Discussions-To''' header if the mailing list to be - used is either [email protected] or [email protected], - or if discussions should be sent to you directly. Most - ''Informational'' PEPs don't have a '''Discussions-To''' header. - - Change the '''Status''' header to "Draft". - - For ''Standards Track'' PEPs, change the '''Type''' header to - ''Standards Track''. - - For ''Informational'' PEPs, change the Type header to - ''Informational''. - - For ''Standards Track'' PEPs, if your feature depends on the - acceptance of some other currently in-development ''PEP'', add a - '''Requires''' header right after the '''Type''' header. The value should - be the '''PEP''' number of the ''PEP'' yours depends on. Don't add this - header if your dependent feature is described in a Final PEP. - - Change the '''Created''' header to today's date. Be sure to follow - the format carefully: it must be in `dd-mmm-yyyy` format, where - the `mmm` is the 3 English letter month abbreviation, e.g. one of - ''Jan'', ''Feb'', ''Mar'', ''Apr'', ''May'', ''Jun'', ''Jul'', ''Aug'', ''Sep'', - ''Oct'', ''Nov'', ''Dec''. - - For ''Standards Track'' PEPs, after the '''Created''' header, add a - '''Python-Version''' header and set the value to the next planned - version of ''Python'', i.e. the one your new feature will hopefully - make its first appearance in. Do not use an alpha or beta - release designation here. Thus, if the last version of ''Python'' - was ''2.2 alpha 1'' and you're hoping to get your new feature into - ''Python 2.2'', set the header to: +== How to Use This Template #howto - '''Python-Version''' 2.2 +<BEPs may include further sections. This is an example.> - - Leave '''Post-History''' alone for now; you'll add dates to this - header each time you post your ''PEP'' to [email protected] or - [email protected]. E.g. if you posted your ''PEP'' to the lists - on ''August 14, 2001'' and ''September 3, 2001'', the - '''Post-History''' header would look like: +Quick edits will consist in following the instructions inside angle brackets (i.e. **<** **>**) . That should be everything needed to write new BEPs. To be more informed about advanced considerations please read the [wiki:/Proposals general content guidelines] and the [wiki:/Proposals/Formats/WikiFormatting WikiFormatting BEP guidelines] . If there is no point in including one of the sections in this document then feel free to remove it. - '''Post-History''' 14-Aug-2001, 03-Sept-2001 +== Backwards Compatibility #backwards-compatibility - - You must manually add new dates and check them in. If you don't - have check-in privileges, send your changes to the ''PEP'' editor. - - Add a '''Replaces''' header if your ''PEP'' obsoletes an earlier PEP. The - value of this header is the number of the ''PEP'' that your new PEP - is replacing. Only add this header if the older ''PEP'' is in - "final" form, i.e. is either ''Accepted'', ''Final'', or ''Rejected''. You - aren't replacing an older open ''PEP'' if you're submitting a - competing idea. - - Now write your '''Abstract''', '''Rationale''', and other content for your - ''PEP'', replacing all this gobbledygook with your own text. Be sure - to adhere to the format guidelines below, specifically on the - prohibition of tab characters and the indentation requirements. - - Update your ''References'' and ''Copyright'' section. Usually you'll - place your ''PEP'' into the public domain, in which case just leave - the '''Copyright''' section alone. Alternatively, you can use the - [http://www.opencontent.org/openpub/ Open Publication License], but public domain is still strongly - preferred. - - Leave the little Emacs turd at the end of this file alone, - including the formfeed character ("!^L", or \f). - - Send your ''PEP'' submission to the ''PEP'' editors ([email protected]), - along with $100k in unmarked pennies. (Just kidding, I wanted - to see if you were still awake. :) +<All BEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The ''BEP'' must explain how to deal with these incompatibilities. ''BEP'' submissions without a sufficient backwards compatibility treatise may be rejected outright. > +== Reference Implementation #reference-implementation -=== Plaintext ''PEP'' Formatting Requirements === +< The reference implementation **must** be completed before any ''BEP'' is given status **Final**, but it need not be completed before the ''BEP'' is accepted. It is better to finish the specification and rationale first and reach consensus on it before writing code. The final implementation **must** include test code and documentation appropriate for either the wiki pages in ''Bloodhound'' users guide or an specific wiki page in the [http://issues.apache.org/bloodhound issue tracker] . > -PEP headings must begin in column zero and the initial letter of each word must be capitalized as in book titles. Acronyms should be in all capitals. The body of each section must be indented 4 spaces. Code samples inside body sections should be indented a further 4 spaces, and other indentation can be used as required to make the text readable. You must use two blank lines between the last line of a section's body and the next section heading. +== References #references -You must adhere to the Emacs convention of adding two spaces at the end of every sentence. You should fill your paragraphs to column 70, but under no circumstances should your lines extend past column 79. If your code samples spill over column 79, you should rewrite them. - -Tab characters must never appear in the document at all. A ''PEP'' should include the standard Emacs stanza included by example at the bottom of this PEP. When referencing an external web page in the body of a ''PEP'', you should include the title of the page in the text, with a footnote reference to the URL. Do not include the URL in the body text of the PEP. E.g. - - Refer to the Python Language web site [1] for more details. - ... - [1] http://www.python.org - -When referring to another ''PEP'', include the ''PEP'' number in the body text, such as "PEP 1". The title may optionally appear. Add a footnote reference, a number in square brackets. The footnote body should include the PEP's title and author. It may optionally include the explicit URL on a separate line, but only in the References section. Note that the `pep2html.py` script will calculate URLs automatically. For example: - - ... - Refer to PEP 1 ![7] for more information about ''PEP'' style - ... [[BR]] [[BR]] - '''References''' [[BR]] [[BR]] - ![7] PEP 1, ''PEP'' Purpose and Guidelines, Warsaw, Hylton - http://www.python.org/dev/peps/pep-0001/ - -If you decide to provide an explicit URL for a ''PEP'', please use this as the URL template: - - http://www.python.org/dev/peps/pep-xxxx/ - -PEP numbers in URLs must be padded with zeros from the left, so as to be exactly 4 characters wide, however ''PEP'' numbers in the text are never padded. - - -== References == +<Provide links to useful resources related to the subject discussed. See sample text below> 1. PEP 1, PEP Purpose and Guidelines, Warsaw, Hylton - http://www.python.org/dev/peps/pep-0001/ + http://www.python.org/dev/peps/pep-0001/ + 2. PEP 9, Sample Plaintext PEP Template, Warsaw + http://www.python.org/dev/peps/pep-0009 2. PEP 12, Sample reStructuredText ''PEP'' Template, Goodger, Warsaw - http://www.python.org/dev/peps/pep-0012/ + http://www.python.org/dev/peps/pep-0012/ 3. http://www.opencontent.org/openpub/ -== Copyright == +== Copyright #copyright -This document has been placed in the public domain. +<In this section all licensing issues should be meticulously exposed . Library and plugin dependencies are among the most important topics . On the other hand each BEP will be explicitly labelled with a copyright statement like shown below, so should not change that. Requests for a different copyright statement have to be posted to [email protected] . For more details consult [wiki:/Proposals#what-belongs-in-a-successful-bep BEP structure explained] .> + +Copyright © 2009-2012 The [http://www.apache.org Apache Software Foundation] [[BR]] +Licensed under the [http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0]. + +Apache Bloodhound, Apache, the Apache feather logo, and the Apache Bloodhound project logo are trademarks of The Apache Software Foundation. -------8<------8<------8<------8<------8<------8<------8<------8<--------
-- Page URL: <https://issues.apache.org/bloodhound/wiki/PageTemplates/Proposals> Apache Bloodhound <https://issues.apache.org/bloodhound/> The Apache Bloodhound (incubating) issue tracker This is an automated message. Someone added your email address to be notified of changes on 'PageTemplates/Proposals' page. If it was not you, please report to .
