__________________________________________________________________
OSEP: 0001
Title: Process proposal: openSUSE Enhancement Proposal
Version: 0.1
Last-Modified: 10 Dec 2013
Author: Jos Poortvliet <jpoortvliet@suse.de>, Antonio Larrosa <alarrosa@suse.de>
Status: Draft
Type: Process
Created: 02 Dec 2013
Post-History:
_____________________________________________________________________
Process proposal: openSUSE Enhancement Proposal
-----------------------------------------------
OSEP (_openSUSE Enhancement Proposal_) is a document providing information
to the openSUSE community or describing a process in Factory or its
environment. The OSEP should provide a concise specification and rationale of
the process it's explaining.
OSEPs are intended to be the primary mechanisms for proposing major new
procedures and for documenting the design decisions that have gone into
Factory. The OSEP author is responsible for building consensus within the
community and documenting dissenting opinions.
Because the OSEPs are maintained as text files in a versioned repository, their
revision history is the historical record of each proposal
footnoteref:[note_repo, https://www.github.com/TBD].
OSEP Types
----------
There are two kinds of OSEP:
- An _Informational OSEP_ describes an issue, or provides general guidelines or
information to the openSUSE developers, but does not propose a new feature.
Informational OSEPs do not necessarily represent a community consensus or
recommendation, so users and implementers are free to ignore Informational
OSEPs or follow their advice.
- A _Process OSEP_ describes a process surrounding Factory, or proposes a change
to a process. They may propose an implementation, but not to packages; they
often require community consensus; unlike Informational OSEPs, they are more
than recommendations, and users are typically not free to ignore them.
Examples include procedures, changes to the decision-making process, and
changes to the tools or environment used in Factory development.
Submitting an OSEP
------------------
The OSEP process begins with a new idea for openSUSE. It is highly recommended
that a single OSEP contain a single key proposal or new idea. Small enhancements
or patches don't need an OSEP.
It's recommended that the author of an OSEP brings his/her idea to key people
from the community to see the acceptance the idea would have before sending it
for review. The received feedback should be introduced in the first draft
document, so that it's as complete as possible and long open-ended discussions
on public mailing lists are avoided.
Once a draft is written in the style described below, it should be presented to
the _opensuse-factory_ mailing list.
OSEPs should be submitted in asciidoc format footnoteref:[asciidoc_userguide,
http://www.methods.co.nz/asciidoc/userguide.html] with UTF-8 codification.
OSEPs may include auxiliary files such as diagrams. Such files must be named
+osep-XXXX-Y.ext+, where _XXXX_ is the OSEP number, _Y_ is a serial number
(starting at 1), and _ext_ is replaced by the actual file extension (e.g.
+png+).
OSEP Review & Resolution
------------------------
Once an author has completed an OSEP, it will be reviewed and discussed at the
Factory mailing list, who will find a consensus to accept or reject it.
Once an OSEP has been accepted, the enhancement has to be implemented.
Once this implementation is complete and accepted, the status will be
changed to _Final_.
An OSEP can also be assigned status _Deferred_. The OSEP author (or in his/her
abscense, the Factory maintainers) can assign the OSEP this status when no
progress is being made for some time. After an OSEP is deferred, it can be
re-assigned to draft status.
An OSEP can also be _Rejected_. Perhaps after all is said and done it was not a
good idea. It is still important to have a record of this fact. The _Withdrawn_
status is similar - it means that the OSEP author themselves has decided that
the OSEP is actually a bad idea, or has accepted that a competing proposal is a
better alternative.
OSEPs can also be superseded by a different OSEP, rendering the original
obsolete (where version 2 of a policy, for example, might replace version 1).
The possible paths of the status of OSEPs are as follows:
image::osep-0001-1.png[OSEP workflow]
Some Informational and Process OSEPs may also have a status of _Active_ if they
are never meant to be completed. E.g. OSEP-0001 (this OSEP).
What belongs in a successful OSEP?
----------------------------------
Each OSEP should have the following parts:
- *Preamble* -- RFC 822 style headers containing meta-data about the OSEP,
including the OSEP number, a short descriptive title (limited to a maximum of
44 characters), the names, and optionally the contact info for each author,
etc.
- *Abstract* -- a short (~200 word) description of the issue being addressed.
- *Copyright/public domain* -- Each OSEP must either be explicitly labeled as
placed in the public domain (see this OSEP as an example) or licensed under
the Open Publication License footnoteref:[note_openpub_license,
http://www.opencontent.org/openpub/].
- *Specification* -- The technical specification should describe the specific
areas of openSUSE that would be touched by this OSEP. If new functionality
is being introduced, what packages will that functionality affect? If new
policy, who will be affected?
- *Motivation and Rationale* -- The motivation is critical for OSEPs that want
to modify the openSUSE distribution. It should clearly explain why the
existing policies are inadequate to address the problem that the OSEP solves.
OSEP submissions without sufficient motivation may be rejected outright.
+
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
enhancement has been done in other distributions.
OSEP Header Preamble
--------------------
Each OSEP must begin with an RFC 822 style header preamble. The headers must
appear in the following order. Headers marked with "*" are optional and are
described below. All other headers are required.
_____________________________________________________________________
OSEP: <OSEP number>
Title: <OSEP title>
Version: <version string>
Last-Modified: <date string>
Author: <list of authors' real names and optionally, email addrs>
Status: <Draft | Active | Accepted | Deferred | Rejected |
Withdrawn | Final | Superseded>
Type: <Informational | Process>
Created: <date created on, in dd-mmm-yyyy format>
Post-History: <dates of postings to opensuse-factory>
* Replaces: <OSEP number>
* Superseded-By: <OSEP number>
______________________________________________________________________
The +Author+ header lists the names, and optionally the email addresses of all
the authors/owners of the OSEP. The format of the Author header value must be
Random J. User <address@dom.ain>
if the email address is included, and just
Random J. User
if the address is not given.
If there are multiple authors, each should be on a separate line following RFC
2822 continuation line conventions. Note that personal email addresses in OSEPs
will be obscured as a defense against spam harvesters.
The +Type+ header specifies the type of OSEP: +Informational+, or +Process+.
The +Created+ header records the date that the OSEP was assigned a number, while
+Post-History+ is used to record the dates of when new versions of the OSEP were
posted to _opensuse-factory_ and/or _opensuse-project_. Both headers should be
in _dd-mmm-yyyy_ format, e.g. _14-Aug-2001_.
OSEPs may also have a +Superseded-By+ header indicating that an OSEP has been
rendered obsolete by a later document; the value is the number of the OSEP that
replaces the current document. The newer OSEP must have a +Replaces+ header
containing the number of the OSEP that it rendered obsolete.
Reporting OSEP Bugs, or Submitting OSEP Updates
-----------------------------------------------
For the early draft stages of the OSEP, it's best to send comments and changes
directly to the OSEP author. For more mature, or finished OSEPs corrections
should be submitted to openSUSE's bugzilla footnoteref:[note_bnc,
https://bugzilla.novell.com/] so that changes don't get lost.
Transferring OSEP Ownership
---------------------------
The Factory maintainers can transfer the ownership of an OSEP to another
author if the original author does no longer have the time or interest in
updating it or follow through with the OSEP process.
Credits
-------
The OSEP concept, and, in fact, much of the text of this document, is liberally
stolen from Python's PEP-0001
footnote:[http://www.python.org/dev/peps/pep-0001/] (by Barry A. Warsaw, Jeremy
Hylton, and David Goodger) and from Gentoo's GLEP-0001
footnote:[http://www.gentoo.org/proj/en/glep/glep-0001.html] (by Grant
Goodyear).
Copyright
---------
This document has been placed in the public domain.