SEP 001 -- SBOL Enhancement Proposals

[graik]

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 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
• 2. Specification of the SEP Workflow
  • 2.1 Drafting an SEP
  • 2.2 SEP Submission
  • 2.3 SEP Discussion and Updates
  • 2.4 Decision
• 3. The SEP document
  • 3.1 SEP Types
  • 3.2 SEP Status
  • 3.3 Document Layout
  • 3.4 Auxiliary Files
• 4. Changes to Voting rules
• 5. Example or Use Case
• 6. 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
• Copyright

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:

• 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

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

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

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:

• 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

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.

[mgaldzic]

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]

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.

[jakebeal]

Labelling as CC0 rather than public domain for better legal compatibility, per discussion with Raik.

[graik]

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.

[mgaldzic]

I like the two author rule as it means that you've had to talk to someone
else before positing it. However given that the gate to SEP positing is
screened via the editors... I do not see a reason for it. I would prefer to
see a responsible Editor listed and contributors acknowledged. For example
something like: http://www.w3.org/TR/2013/NOTE-prov-primer-20130430/ Much
like with the W3C documents, sometimes it just editors.

On Thu, Oct 15, 2015 at 11:14 AM Raik Grünberg notifications@github.com
wrote:

I am not sure about the two-author requirement. E.g. we currently only
have a single author on SEP #3
#3 and nobody seems to be
concerned by that. Besides, in the python world, there are many
single-author PEPs.

—
Reply to this email directly or view it on GitHub
#1 (comment).

[jakebeal]

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.

[graik]

I like the idea of listing the editor who posted the SEP in an extra field
at the top. Like in most journal articles. And then remove the two-author
requirement. Any dissenting opinions?

[bbartley]

Fine with me.
B

[graik]

Updated the draft, removing the two author requirement.

[graik]

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.

[graik]

Inserted instructions of how to submit a SEP through a github pull request.

[graik]

Voting has closed on March 10th 2016 (after prolongation). SEP #1 was accepted.
Total votes: 25
Accept: 25

[palchicz]

Closing in accordance with changes to SEP issue tracking rules detailed in SEP 001 bcbbcab#diff-44cec2aabf4c066f9a54ac4ef6634b9b