Home Wiki > openSUSE:OSEP 0001
Sign up | Login

openSUSE:OSEP 0001

tagline: From openSUSE

__________________________________________________________________
 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.