Permalink
Browse files

Copy SEP001 from issue tracker to repository

  • Loading branch information...
udp committed Oct 18, 2018
1 parent 3e598bf commit 25a09f4b96ce5868a9add128e040eaedae7bc48c
Showing with 165 additions and 0 deletions.
  1. +165 −0 sep_001.md
@@ -0,0 +1,165 @@
# SEP 001 -- SBOL Enhancement Proposals
| SEP | 001 |
| --- | --- |
| **Title** | SBOL Enhancement Proposals |
| **Authors** | Raik Grünberg (raik.gruenberg at gmail com), Bryan Bartley (bartleyba at sbolstandard org) |
| **Editor** | Raik Grünberg |
| **Type** | Procedure |
| **Status** | Accepted |
| **Created** | 05-Oct-2015 |
| **Last modified** | 20-Feb-2016 |
## Abstract
SEP stands for [SBOL](http://sbolstandard.org) Enhancement Proposal. A SEP is a design document providing information to the SBOL community. It may describe a new feature or term for the SBOL data model or a rule or organizational process that the SBOL community should follow. The SEP should provide the rationale and a concise technical specification of the feature.
We intend SEPs to be the primary mechanisms for proposing major data model changes, for collecting community input on an issue, and for documenting the design decisions that have gone into SBOL. The SEP authors are responsible for building consensus within the community and documenting dissenting opinions.
SEPs are filed by SBOL editors in a dedicated issue tracker on github. If not withdrawn, an SEP will eventually be put to a vote by the SBOL community.
## Table of Content
- [1. Rationale](#rationale)
- [2. Specification of the SEP Workflow](#specification)
- 2.1 Drafting an SEP
- 2.2 SEP Submission
- 2.3 SEP Discussion and Updates
- 2.4 Decision
- [3. The SEP document](#document)
- 3.1 SEP Types
- 3.2 SEP Status
- 3.3 Document Layout
- 3.4 Auxiliary Files
- [4. Changes to Voting rules](#voting)
- [5. Example or Use Case](#example)
- [6. Discussion](#discussion)
- 6.1 current versus new issue tracker
- 6.2 Filtering by editors
- 6.3 Should we reserve the first 10 or 20 SEP numbers for important SBOL government rules?
- [References](#references)
- [Copyright](#copyright)
## 1. Rationale <a name="rationale"></a>
With the growth of SBOL in terms of both scope and members, building consensus through informal mailing list discussions and SBOL meetings is becoming increasingly inefficient. Only a minority of SBOL participants is watching a given mailing list thread or present for an actual meeting. This makes it often difficult for others to "catch up" with an ongoing discussion and also leads to many circular debates that are recurring with some regularity or quickly move off-topic.
SBOL Enhancement Proposals (SEPs) address many of these issues. SEPs are borrowing heavily from Python Enhancement Proposals (PEPs) [[1](https://www.python.org/dev/peps/pep-0001)] which are the main avenue to proposing and managing changes to the Python programming language. The PEP process has been used and refined by the Python developer community over many years and we hope to benefit from this experience.
SEPs have the following goals:
- Manage proposed changes to the SBOL data model.
- Resolve long open-ended discussions
- Distinguish between real issues versus informal suggestions
- Summarize arguments **for** and **against** a proposed change
- Introduce newcomers and bystanders to an issue under discussion
- Formalize the drafting of voting ballots with community input
- Document history of decision-making in the SBOL community
By drafting proposals as a shared document, the SEP process is intended to help integrate the diverse opinions and perspectives presented in a discussion thread. It encourages consensus-making by forcing co-authors of a proposal to consolidate their opinions around the strongest points of agreement while resolving minor points of contention. Authors of a proposed change will be motivated to acknowledge, summarize, and address contrary points of view other than their own.
## 2. Specification of the SEP Workflow <a name="specification"></a>
### 2.1 Drafting an SEP
The SEP process begins with a new idea for improving SBOL. It is highly recommended that a single SEP contain only a single key proposal or new idea. The more focused the SEP, the more successful it tends to be. The SBOL editors reserve the right to reject SEP proposals if they appear too unfocused or too broad. If in doubt, split your SEP into several well-focused ones.
The SEP authors or author write the SEP using the style and format described below, shepherd the discussions in the appropriate forums, and attempt to build community consensus around the idea.
The SEP champion (a.k.a. author) should first attempt to ascertain whether the idea is SEP-able. Posting to the sbol-dev@googlegroups.com mailing list is currently the best way to go about this. Vetting an idea publicly before going as far as writing a SEP is meant to save the potential author time. It also helps to make sure the idea is applicable to the entire community and not just the author.
The author then writes up a plain text document, based on the template provided as SEP #2, summarizing their proposal as succinctly and clearly as possible (see below for details).
### 2.2 SEP Submission
Following a discussion on sbol-dev or other channels (e.g. during an SBOL workshop), the proposal should be sent as a draft SEP to the SBOL editors < sbol-editors@googlegroups.com >. The draft must be written in SEP style as described below, else it will be sent back without further regard until proper formatting rules are followed (although minor errors will be corrected by the editors). Alternatively, the SEP may be submitted as a github pull request:
1. **fork** https://github.com/SynBioDex/SEPs into your own user space
2. open the sep_002_template.md document in RAW view and download/save the file locally ( or follow this link: https://raw.githubusercontent.com/SynBioDex/SEPs/master/sep_002_template.md)
3. rename sep_002_template.md and upload it back to your forked repository
4. Edit your SEP directly on github
5. Initiate a **pull request** for your version of the repository on https://github.com/SynBioDex/SEPs
If approved, an editor will submit the SEP to the dedicated github issue tracker, for which only SBOL editors have write-access. The github issue number then becomes the SEP number by which the proposal can be referenced. The SBOL editors will _not_ unreasonably deny a SEP. Reasons for denying SEP status include duplication of effort, being technically unsound, not providing proper motivation or not addressing backwards compatibility.
### 2.3 SEP Discussion and Updates
Authors are explicitly encouraged to update their SEP as the discussion progresses and their ideas are refined. As updates are necessary, the SEP author(s) can email new SEP versions to the SBOL editors, who will update the issue accordingly.
The editors may invite, at their own discretion, other SBOL community members to formulate a short paragraph which will then be added to the discussion section in order to better document dissenting opinions. However, SEP authors are asked to fairly document dissent themselves so that "dissenting voice" paragraphs will hopefully be rarely needed.
### 2.4 Competing SEPs
This is simply a list of any open SEPs that offer a competing or contradictory proposal. Simply by listing a competing SEP, the authors indicate acknowledgement of competing viewpoints. This should help Editors shepherd the progress of the SBOL community toward meaningful votes that provide clear, contrasting options to voters in the SBOL Developers community.
### 2.5 Decision
Eventually, an SEP is either withdrawn by the authors or put to a vote by the SBOL Editors (or any two developers). The exact voting procedure is described in SEP #5. If approved, the SEP will be marked as “Accepted”. Once a change is implemented, the status changes to “Final”. Approved procedural SEPs (e.g. concerning SBOL governing rules) are labelled as "Active", indicating that this rule may be further adapted in the future.
All SEPs will always remain "Open" on the issue tracker so that they are all visible by default. Editors attach and update issue labels to allow easy filtering for SEP Type and Status.
## 3. The SEP document <a name='document'></a>
### 3.1 SEP Types
There are two types of SEPs:
- data model -- a proposal to change or expand the SBOL data model
- process -- a proposal of how to improve SBOL governance or management
### 3.2 SEP Status
Every SEP starts out in “Draft” status. A draft can be: “Accepted”, “Rejected” or “Withdrawn”. A draft may also be “Deferred” if a discussion is deemed to be postponed. After their implementation, a SEP is labelled as “Final”. Later during the life cycle of an SEP it may be “Replaced” or “Deprecated”. Process SEPs are instead labelled “Active”.
### 3.3 Document Layout
An SEP is described as a text document using (github-flavoured) Markdown syntax. A boilerplate template for writing a new SEP will be provided as SEP #2. The document must have the following sections (optional sections or lines given in "[ ]"):
1. Preamble
- SEP number (assigned by editor, leave empty or XXX)
- descriptive title (limited to a maximum of 44 characters)
- names for each author
- created (date)
- Type of SEP (data model | process; process = SBOL organization or “governing rule”)
- [SBOL version] (version to which change should be introduced; if type == data model)
- [Replaces] (SEP number, only if this SEP is Final/Accepted and replaces another one)
- Status (Draft | Accepted | Rejected | Withdrawn | Deferred | Final | Active)
2. Abstract -- a (very) short (~200 words, at most) summary of the proposed change or enhancement.
3. Motivation (or Rationale) -- The motivation / rationale for the proposed change and how it fits in with the mission and vision of the SBOL standard as the authors see it.
4. Specification (title may differ)-- The technical specification should describe the syntax and semantics of any new SBOL feature. The specification may include UML but this is not required. The specification can have sub-headings as required/useful. The name of this section may differ (especially for procedure SEPs).
5. Example or Use Case [optional but recommended] -- process or more trivial proposals may choose to skip this section. Data model changes **must** list a short example or use case.
6. Backwards Compatibility [optional] -- All SEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The SEP must explain how the author proposes to deal with these incompatibilities.
7. Discussion -- Summarize any relevant discussion, in particular counter-arguments brought up.
References are listed at the end. A copyright statement should place the document in the public domain. Authors may choose to change or introduce additional top-level sections but should follow this layout as closely as possible.
### 3.4 Auxiliary Files
SEPs may include auxiliary files such as diagrams. Such files must be named sep-XXX-Y.ext , where "XXX" is the SEP number, "Y" is a serial number (starting at 1), and "ext" is replaced by the actual file extension (e.g. "png"). Editors will attach these files to the github issue.
## 4. Changes to SBOL voting rules <a name='voting'></a>
SBOL governance rules laid out on http://sbolstandard.org/development/gov/ currently do not mention SEPs. They state that any two members of the mailing list can put any change proposal to a vote. Implementing SEP #1 means the governance page needs to be adapted. The necessary changes to the sections **Voting process** and **Voting form** are described in SEP #5.
## 5. Example or Use Case <a name='example'></a>
SEP 1 serves as first example of a SEP and the SEP adoption process.
## 6. Discussion <a name='discussion'></a>
### 6.1 current versus new issue tracker
This proposal is a further evolution step from the current informal (and still relatively recent) practice of submitting issues on the synbiodex / SBOL-specification issue tracker. Several SBOL members expressed the opinion this informal issue tracker is sufficient. The SBOL-specification repo hosts the official SBOL specification document. Issues submitted to the repository can refer both to the document itself (e.g. issues in the description of SBOL or other technical problems) as well as actual issues with the current SBOL specification. Some key differences to the current practice are:
- create a dedicated repo / issue tracker only for SEPs
- editor-only write access -- this introduces a social filter that, we think, should be important in moderating and filtering the discussion and will improve the quality of proposals
- prescription of an official proposal template -- promoting minimal documentation standards
- formalized and transparent process of decision making
Compared to informal issues that can be quickly registered by any developer, SEPs introduces quite some documentation overhead. To some extend, this is intentional and meant to force everyone taking at least one big breath before suggesting SBOL overhauls. It may however create an unwanted barrier to reporting smaller issues people encounter when implementing SBOL. We have to see how this plays out in practice. The synbiodex / sbol-specification issue tracker may still be useful to quickly keep track of potential issues before escalating any of them to more formal change requests / SEPs.
A dedicated repo has the added advantage that we can later decide to also to put SEP documents under version control by committing them as *.md documents in this repository. That's the way PEPs are organized.
### 6.2 Filtering by editors
In Python, core developers can choose to submit a PEP directly. We believe going through an editor is an important social filter to ensure we are not overrun by too many requests of low quality.
### 6.3 Should we reserve the first 10 or 20 SEP numbers for important SBOL government rules?
In Python, PEP 1 - 100 have been reserved for community - related process issues. After discussion among the editors, we opted against this as it is not easy to realize using the github issue tracker.
### 6.4 Should we insist on at least two SEP authors?
The classic SBOL decission making process always requires two people to suggest anything for a vote. In case of SEPs, the editors act as an additional "gate" so that a second author may not always be needed.
## References <a name='references'></a>
## Copyright <a name='copyright'></a>
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
<a rel="license"
href="http://creativecommons.org/publicdomain/zero/1.0/">
<img src="http://i.creativecommons.org/p/zero/1.0/88x31.png" style="border-style: none;" alt="CC0" />
</a>
<br />
To the extent possible under law,
<a rel="dct:publisher"
href="sbolstandard.org">
<span property="dct:title">SBOL developers</span></a>
has waived all copyright and related or neighboring rights to
<span property="dct:title">SEP 001</span>.
This work is published from:
<span property="vcard:Country" datatype="dct:ISO3166"
content="US" about="sbolstandard.org">
United States</span>.
</p>

0 comments on commit 25a09f4

Please sign in to comment.