SEP 001 -- SBOL Enhancement Proposals #1
Comments
|
I support the idea behind the SEP process. SEP001 nicely lays out the full possibilities for what can go in a SEP document. Suggestion, I think these instructions should make clear "What are the minimally required sections?" |
graik
changed the title
|
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. |
|
Labelling as CC0 rather than public domain for better legal compatibility, per discussion with Raik. |
|
I am not sure about the two-author requirement. E.g. we currently only have a single author on SEP #3 and nobody seems to be concerned by that. Besides, in the python world, there are many single-author PEPs. |
|
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 [email protected]
|
|
I concur, as the listed author of SEP 003. I didn't know what to do about names given that we'd discussed it in a general session. People present indicated general approval, but I wasn't sure whether that should mean that they were authors or not. |
|
I like the idea of listing the editor who posted the SEP in an extra field |
|
Fine with me. |
|
Updated the draft, removing the two author requirement. |
|
Small update to section 2.5: "The exact voting procedure is described in SEP #5." I will propose a vote on SEP 1 and 5 together. To be discussed among editors first. |
|
Inserted instructions of how to submit a SEP through a github pull request. |
|
Voting has closed on March 10th 2016 (after prolongation). SEP #1 was accepted. |
|
Closing in accordance with changes to SEP issue tracking rules detailed in SEP 001 bcbbcab#diff-44cec2aabf4c066f9a54ac4ef6634b9b |
SEP 001 -- SBOL Enhancement Proposals
Abstract
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
1. Rationale
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] 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. Specification of the SEP Workflow
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 [email protected] 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 < [email protected] >. 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.
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
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.
4. Changes to SBOL voting rules
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
SEP 1 serves as first example of a SEP and the SEP adoption process.
6. Discussion
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.
References
Copyright
To the extent possible under law, SBOL developers has waived all copyright and related or neighboring rights to SEP 001. This work is published from: United States.
The text was updated successfully, but these errors were encountered: