Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
SEP 001 -- SBOL Enhancement Proposals #1
SEP 001 -- SBOL Enhancement Proposals
SEP stands for SBOL 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
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)  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:
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.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 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 < email@example.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:
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.
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.1 SEP Types
There are two types of SEPs:
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 "[ ]"):
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.
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.
SEP 1 serves as first example of a SEP and the SEP adoption process.
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:
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.
So far, everything that is not explicitly labelled [optional] would be required. I've tried to make that more obvious. So right now minimally required would be: Preamble, Abstract, Specification, Discussion, Copyright. Though, in the Python world I have seen PEPs that basically only have a single-line abstract and then one single paragraph without any sections. But those are the exception.
I like the two author rule as it means that you've had to talk to someone
On Thu, Oct 15, 2015 at 11:14 AM Raik Grünberg firstname.lastname@example.org