summaryrefslogtreecommitdiff
path: root/KEP-0001.txt
blob: fed98a8a8858e539bc2323c9c7642ac73f9fa5ee (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
{{kep
 |number=1
 |ticketnumber=29
 |title=Bootstrap the KEP Process
 |author=Georg Greve
 |author_email=greve@kolabsys.com
 |status=approved
 |type=process
 |creation_date=2010-11-16
 |obsoleted_by=
 |related=
}}

__TOC__

== Abstract ==

KEP stands for Kolab Enhancement Proposal. A KEP is modeled closely after the Python Enhancement Proposal process <ref name="PEP-1">{{cite web|url=http://www.python.org/dev/peps/pep-0001 |title=PEP 1, PEP Purpose and Guidelines |last=Warsaw |first=Hylton}}</ref>. A Kolab Enhancement Proposal is a design document providing information to the Kolab community, or describing a new feature for the Kolab Groupware Solution or its processes or environment. The KEP should provide a concise technical or procedural specification of the feature and a rationale for the feature.

Some of the most important benefits of the KEPs are to (a) require ideas to be fully thought out, (b) communicate a change to those who did not participate in the discussion, (c) document it for future reference and use by new members of our community and (d) facilitate community based decision making.  We intend KEPs to be the preferred mechanisms for documenting the design decisions that have gone into Kolab after its re-launch in 2010 as well as proposing new features, for collecting community input on an issue. The KEP author is responsible for building consensus within the community and documenting dissenting opinions.

Because the KEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This historical record is available in the KEP GIT repository provided by Kolab Systems. The information is available via GIT web access [http://git.kolabsys.com/keps/ here].

{{note|The GIT repository and secretariat list will be moved to the kolab.org infrastructure once the infrastructure reworking is complete.}}

== KEP Types ==

There are four kinds of KEP:

# A '''Design KEP''' describes a change to the Kolab Storage Format or other central design questions.
# A '''Technology KEP''' describes a change to the integrated technologies.
# An '''Informational KEP''' describes a Kolab design issue, or provides general guidelines or information to the Kolab community, but does not propose a new feature. Informational KEPs do not necessarily represent a Kolab community consensus or recommendation, so users and implementors are free to ignore Informational KEPs or follow their advice.
# A '''Process KEP''' describes a process surrounding Kolab, or proposes a change to (or an event in) a process. Process KEPs are like Format KEPs but apply to areas other than the Kolab Groupware Solution itself. They may propose an implementation, but not to Kolab's codebase; they often require community consensus; unlike Informational KEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Kolab development. Any meta-KEP is also considered a Process KEP.

== KEP Process ==

The KEP Process began with a rough approximation of the PEP process, excluding the forms of markup and headers, with Kolab Systems providing the infrastructure and reference point. The authoritative address to send KEPs is [mailto:kep-secretariat@lists.kolabsys.com kep-secretariat@lists.kolabsys.com], after which discussion will take place on the appropriate list.

The life cycle of a KEP is

=== Creation ===

* A new draft KEP is sent to [mailto:kep-secretariat@lists.kolabsys.com kep-secretariat@lists.kolabsys.com] with the request to assign a number for this KEP. The following header fields are mandatory:
** TITLE of the KEP, which should be as descriptive and summarizing as possible
** AUTHOR(S) of the KEP who are involved in the drafting and volunteer to drive the process. If there are multiple authors they should agree on a primary author who should be listed first.
** TYPE of the KEP, according to the types listed and explained above.
** MAILINGLIST that will be canonical for discussion of this KEP. In principle, any English speaking public mailing list for Kolab can be chosen, the following lists are recommended for the various types of KEP:
*** '''Design KEP''' are typically discussed on [mailto:kolab-format@kolab.org kolab-format@kolab.org]
*** '''Technology KEP''' are typically discussed on [mailto:kolab-devel@kolab.org kolab-format@kolab.org]
*** '''Informational KEP''' are typically discussed on [mailto:kolab-devel@kolab.org kolab-format@kolab.org]
*** '''Process KEP''' are typically discussed on [mailto:kolab-devel@kolab.org kolab-format@kolab.org]
** (if applicable) KEPs that are going to be obsoleted/replaced by this KEP.
* The secretariat assigns the next sequential number to this KEP, ensures the formatting is correct, all header fields are provided and places the file in the [http://git.kolabsys.com/keps/ GIT repository], ensuring the author(s) have access.
* The primary author then places the draft in their personal namespace on wiki.kolab.org, the recommended naming is /User:<NAME>/Drafts:KEP:<NUMBER>
* The primary author then announces and introduces the draft KEP to the canonical mailing list for discussion, resending this mail to other public Kolab mailing lists as required. One copy should always go to [mailto:kolab-devel@kolab.org kolab-devel@kolab.org].

=== Discussion and Finalization ===

* The KEP will be discussed on the most appropriate public mailing list.
* The author(s) have the obligation to consider each substantive submission and comment, to judge it carefully and on its technical/substantive merits, and to try and incorporate it in the most constructive, inclusive and consensus building manner.
* While all kinds of comments are welcome, opposing views owe it to the author(s) to have given good consideration to the aspects raised in the KEP. Depending on the kind of KEP, this means qualified opposition must meet certain minimum criteria:
** For opposition to be technically qualified, it should be based on the KEP and its references, and make a topical technical point disproving any particular part of the KEPs argument, conclusion or decision.
** For opposition to be procedurally qualified, it should be based on procedural questions and concerns, as well as accompanied by an improvement proposal.
* As the drafting continues, the author(s) will continue to work in feedback, bringing the document to a consensus opinion, providing updated drafts through wiki.kolab.org, as sensible, helpful and appropriate to facilitate good and timely consensus building.
* KEPs are adopted by consensus in the form of lack of sustained, qualified opposition.
* When a KEP has been thoroughly discussed, either on public list before it has become formalized, or in its drafting stage, the secretariat should then issue a "closing call" for the KEP pointing to the version to be accepted as a '''revision-specific link''' and stating the deadline by which it will be considered adopted. This deadline should be
** '''two weeks''' after the closing call for all KEP that are based on more than '''six weeks''' of discussion on the respective public mailing lists, either before they became formalized as KEP, or after, and
** '''six weeks''' for all KEP that have been discussed shorter.
* When the closing call is issued, the KEP should be moved into the authoritative name space on wiki.kolab.org/KEP:<NUMBER> and while the authors can continue to work on the version in git, updates of the authoritative version should now go through the secretariat.
* The closing call should go to the canonical discussion mailing list, as well as all public mailing list that seem sensible and relevant and all likely affected Authoritative Component Contacts (see below). kolab-devel@kolab.org shall always be informed. 
* In reaction to the closing call, any member of the Kolab community or of affected components can request a two week extension for important reasons with the secretariat. This extension will be granted once for any KEP.
* If there is sustained, qualified opposition (as described above) after the closing call, the author(s) must take that into account in the best way possible, potentially documenting sustained opposition in the KEP. Afterwards, the author(s) shall request another closing call from the secretariat.

=== Adoption, Rejection and Retraction ===

* If there was no qualified opposition to a closing call on a KEP within the deadline set by the secretariat, the KEP has been formally adopted and its status will be changed to 'accepted'.
* The author(s) of a KEP can at any point in time retract their proposal, the KEP will then be considered closed, its status will be changed to 'retracted'.
* If a KEP fails to gain acceptance within '''one calendar year''' after it was initially proposed, its status shall be changed to 'rejected'. A new KEP with a similar proposition can then be requested by the same author(s) or others.

=== Replacement, Retirement ===

* If a KEP is no longer relevant to Kolab, the secretariat shall send a note of 'pending retirement' to the canonical mailing list on which it was discussed, as well as kolab-devel@kolab.org (if not identical) with no less than '''six weeks''' of notice period for opposition. If no opposition is received, the KEP shall be deemed 'retired' and of purely historical interest.
* If a KEP has been replaced by another KEP which has been duly accepted, its status shall be set to 'replaced'.

=== Implementation & Followup ===

* Once a KEP has been accepted, an issue shall be created in the public Kolab Systems issue tracker instance for this KEP, linking to the official KEP location '''as a revision-specific link''', as well as containing the abstract and the likely affected components.
* All likely affected Authoritative Component Contacts shall be added to the recipient list of this issue to ensure they receive the information about the KEP and can incorporate it into their workflow accordingly.
* The issue is then split for the various issues for components that are tracked on the Kolab Systems issue tracker.
* The issues shall then be normally resolved, and be re-opened upon potential modification of the KEP, again pointing to the new version as a revision-specific link.

== The Secretariat ==

* The secretariat should consist of volunteers who are '''not''' currently active in the KEP process as authors or discutants and shall understand their role as a purely faclitatory one. Any member of the Kolab community can volunteer for the secretariat, and shall be held in high honors for helping with this important task.

* In absence of volunteers who are not themselves active authors or participating in the discussions, it shall deemed acceptable to have author participate in the secretariat. In no case shall an active author of a KEP perform the secretariat duties for their own KEP in question.

* '''Authoritative Component Contact''': As the Kolab Groupware Solution incorporates many technologies and integrates with many up- and downstream projects, a Design or Technology KEP can likely result in changes to various components, which often will have their own issue tracking, each of which might see changes in multiple components. So one KEP could easily lead to multiple tickets in several issue trackers. In order to ensure that all affected components receive information regarding KEPs that are likely to affect them, all components shall have designated contact addresses (either individuals or mailing lists) that should receive information about relevant KEPs.

== KEPs and the Server Release Process ==

* The accepted and latest draft versions of all KEPs shall be tagged with each release of the server of the Kolab Groupware Solution, documenting which state of the KEPs has gone into a certain release, and forming part of the documentation of the Kolab Groupware Server.

== References ==

{{Reflist}}

== Copyright ==

This document has been placed in the public domain.