summaryrefslogtreecommitdiff
path: root/KEP-0004.txt
blob: c17743f9b9e0498cbaaab3faa7a1dc49dea1db68 (plain)
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
{{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}}