summaryrefslogtreecommitdiff
path: root/KEP-0004.txt
diff options
context:
space:
mode:
authorGeorg Greve <greve@katana.(none)>2010-11-23 08:58:24 (GMT)
committerGeorg Greve <greve@katana.(none)>2010-11-23 08:58:24 (GMT)
commit0362860264c18ffff8499400db702c52cd3efaf0 (patch)
treeef1d4915521f6660300bf05c6e9c3377dc1d09cb /KEP-0004.txt
parent2a3589f8ad5f18e67a02f81c40802a0050ecd5dd (diff)
downloadkeps-0362860264c18ffff8499400db702c52cd3efaf0.tar.gz
First revision of KEP #4, as submitted by Jeroen van Meeuwen
Diffstat (limited to 'KEP-0004.txt')
-rw-r--r--KEP-0004.txt117
1 files changed, 117 insertions, 0 deletions
diff --git a/KEP-0004.txt b/KEP-0004.txt
new file mode 100644
index 0000000..c17743f
--- /dev/null
+++ b/KEP-0004.txt
@@ -0,0 +1,117 @@
+{{kep
+ |number=4
+ |ticketnumber=32
+ |title=KEP Formatting Guidelines
+ |author=Jeroen van Meeuwen
+ |author_email=vanmeeuwen at kolabsys.com
+ |status=draft
+ |type=informational
+ |creation_date=2010-11-18
+ |obsoletes=
+ |obsoleted_by=
+ |related=
+}}
+
+== Abstract ==
+
+To formalize the format in which KEPs are proposed and updated, consistency across KEPs is preserved and differences in the KEP authors' (mark-up) styles minimized.
+
+== Compliance with <nowiki>RFC 2119</nowiki> ==
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in {{rfc|2119}}<ref name="rfc2119">{{rfc|2119|title=Key words for use in RFCs to Indicate Requirement Levels}}</ref>.
+
+== References to RFCs ==
+
+RFCs are to be referenced by the string "RFC" followed by a space character, followed by the RFC NUMBER, and optionally with the TITLE, as follows, to ensure the links are correct, properly formatted and issued as a reference.
+
+ <nowiki>{{rfc
+ |NUMBER
+ |title=Title
+ }} <ref name="rfcNUMBER">{{rfc|NUMBER|title=TITLE}}</ref>
+ </nowiki>
+
+{{note|Specifying the <nowiki>RFC 3</nowiki> times?|Templates in MediaWiki appear to not nest all too well. Listing the RFC only once, like MediaWiki tends to intelligently parse (example: RFC 5464) however, do not show in printed versions of the KEP Book.}}
+
+== KEP Process and Metadata Headers ==
+
+A KEP '''MUST''' contain the following headers at the very start of the text file:
+
+ <nowiki>{{kep
+ |number=NUMBER
+ |ticketnumber=TICKETNUMBER
+ |title=TITLE
+ |author=AUTHOR FULL NAME
+ |author_email=AUTHOR EMAIL ADDRESS
+ |status=STATUS
+ |type=TYPE OF KEP
+ |creation_date=TODAY
+ }}</nowiki>
+
+where the following capitalized strings stand for;
+
+; '''NUMBER'''
+: The number that is to be assigned by the KEP Secretariat. Do not edit.
+; '''TICKETNUMBER'''
+: The corresponding ticket number, that is also to be assigned by the KEP Secretariat. Do not edit.
+; '''AUTHOR FULL NAME'''
+: The author's full name.
+; '''AUTHOR EMAIL ADDRESS'''
+: The author's email address.
+; '''STATUS'''
+: The status of the KEP, one of 'draft', 'deferred', 'approved', 'rejected' or 'obsolete'.
+; '''TYPE OF KEP'''
+: The type of KEP; one of 'process', 'technical', 'informational' or 'design', as described in [[KEP:1]]
+; '''TODAY'''
+: The date formatted as YYYY-MM-DD
+
+Additionally, the following lines may be added:
+
+ |coauthor1=CO-AUTHOR FULL NAME
+ |coauthor1_email=CO-AUTHOR EMAIL ADDRESS
+ |obsoletes=OBSOLETES_NUMBER(S)
+ |related=RELATED_NUMBERS
+
+each of which indicates the following:
+
+; '''CO-AUTHOR FULL NAME'''
+: The full name of the co-author. Repeat with incremental numbers to list more co-authors. Each co-author listed '''MUST''' have a corresponding email address.
+; '''CO-AUTHOR EMAIL ADDRESS'''
+: The email address of the co-author. Repeat with incremental numbers to list more co-authors. The number of email addresses '''MUST''' correspond with the number of co-authors listed.
+; '''OBSOLETES_NUMBER(S)'''
+: If any other KEPs are to be obsoleted by the proposed KEP, list their numbers here in a comma-separated list (no spaces!).
+; '''RELATED_NUMBER(S)'''
+: If any KEPs are related to the proposed KEP, list their numbers here in a comma-separated list (no spaces!).
+
+== Formatting the Document ==
+
+The highest level of headers used in the KEP is 2 (two): This means headers may be formatted as:
+
+ <nowiki>== Abstract ==</nowiki>
+
+or:
+
+ <nowiki>=== Rationale ===</nowiki>
+
+but '''NOT''':
+
+ <nowiki>= References =</nowiki>
+
+Top-level headers are reserved for use throughout templates associated with the KEP wiki page.
+
+=== Minimal Contents ===
+
+The minimal contents of any type of KEP are, in terms of section headers:
+
+# Abstract
+# References
+# Copyright
+
+== Listing References ==
+
+List references using the following template:
+
+ <nowiki>{{Reflist}}</nowiki>
+
+== References ==
+
+{{Reflist}}