{"action":"created","issue":{"url":"https://api.github.com/repos/SynBioDex/SEPs/issues/1","labels_url":"https://api.github.com/repos/SynBioDex/SEPs/issues/1/labels{/name}","comments_url":"https://api.github.com/repos/SynBioDex/SEPs/issues/1/comments","events_url":"https://api.github.com/repos/SynBioDex/SEPs/issues/1/events","html_url":"https://github.com/SynBioDex/SEPs/issues/1","id":110357085,"number":1,"title":"SEP 001 -- SBOL Enhancement Proposals","user":{"login":"graik","id":1862877,"avatar_url":"https://avatars.githubusercontent.com/u/1862877?v=3","gravatar_id":"","url":"https://api.github.com/users/graik","html_url":"https://github.com/graik","followers_url":"https://api.github.com/users/graik/followers","following_url":"https://api.github.com/users/graik/following{/other_user}","gists_url":"https://api.github.com/users/graik/gists{/gist_id}","starred_url":"https://api.github.com/users/graik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graik/subscriptions","organizations_url":"https://api.github.com/users/graik/orgs","repos_url":"https://api.github.com/users/graik/repos","events_url":"https://api.github.com/users/graik/events{/privacy}","received_events_url":"https://api.github.com/users/graik/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/SynBioDex/SEPs/labels/Draft","name":"Draft","color":"fbca04"},{"url":"https://api.github.com/repos/SynBioDex/SEPs/labels/Type:%20Procedure","name":"Type: Procedure","color":"c7def8"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":5,"created_at":"2015-10-08T02:01:21Z","updated_at":"2015-10-15T18:29:32Z","closed_at":null,"body":"SEP 001 -- SBOL Enhancement Proposals\r\n===================================\r\n\r\nSEP                     | 001\r\n----------------------|--------------\r\n**Title**                | SBOL Enhancement Proposals\r\n**Authors**           | Raik Grünberg (raik.gruenberg at gmail com), Bryan Bartley (bartleyba at sbolstandard org)\r\n**Type**               | Procedure\r\n**Status**             | Draft\r\n**Created**          | 05-Oct-2015\r\n**Last modified**  | 07-Oct-2015\r\n\r\nAbstract\r\n-----------\r\n\r\nSEP 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. \r\n\r\nWe 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.\r\n\r\nSEPs 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.\r\n\r\nTable of Content\r\n---------------------\r\n\r\n* [1. Rationale](#rationale)\r\n* [2. Specification of the SEP Workflow](#specification)\r\n  * 2.1 Drafting an SEP\r\n  * 2.2 SEP Submission\r\n  * 2.3 SEP Discussion and Updates\r\n  * 2.4 Decision\r\n* [3. The SEP document](#document)\r\n  * 3.1 SEP Types\r\n  * 3.2 SEP Status\r\n  * 3.3 Document Layout\r\n  * 3.4 Auxiliary Files\r\n* [4. Example or Use Case](#example)\r\n* [5. Discussion](#discussion)\r\n  * 5.1 current versus new issue tracker\r\n  * 5.2 Filtering by editors\r\n  * 5.3 Should we reserve the first 10 or 20 SEP numbers for important SBOL government rules?\r\n* [References](#references)\r\n* [Copyright](#copyright)\r\n\r\n1. Rationale <a name=\"rationale\"></a>\r\n----------------\r\n\r\nWith 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.\r\n\r\nSBOL 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.\r\n\r\nSEPs have the following goals:\r\n\r\n* Manage proposed changes to the SBOL data model.\r\n* Resolve long open-ended discussions\r\n* Distinguish between real issues versus informal suggestions\r\n* Summarize arguments **for** and **against** a proposed change\r\n* Introduce newcomers and bystanders to an issue under discussion\r\n* Formalize the drafting of voting ballots with community input\r\n* Document history of decision-making in the SBOL community\r\n\r\nBy 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.\r\n\r\n2. Specification of the SEP Workflow <a name=\"specification\"></a>\r\n----------------------------------------------\r\n\r\n### 2.1 Drafting an SEP\r\n\r\nThe 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.\r\n\r\nEach SEP must have at least two authors, although more authors may contribute.  The primary advocate or \"champion\" writes the SEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea.  A second author is required to indicate that a minimum threshold of consensus in regards to the proposal has been met. This is in the spirit of SBOL governance rules which requires all motions to be seconded before consideration.\r\n\r\nThe 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.\r\n\r\nThe authors then write 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).\r\n\r\n### 2.2 SEP Submission\r\n\r\nFollowing 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).\r\n\r\nIf 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 addressing backwards compatibility.  \r\n\r\n### 2.3 SEP Discussion and Updates\r\n\r\nAuthors 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.\r\n\r\nThe 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.\r\n\r\n### 2.4 Competing SEPs\r\n\r\nThis 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.\r\n\r\n### 2.5 Decision\r\n\r\nEventually, an SEP is either withdrawn by the authors or the SBOL editors put it to a vote. 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.\r\n\r\nAll 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.\r\n\r\n3. The SEP document <a name='document'></a>\r\n----------------------------\r\n\r\n### 3.1 SEP Types\r\n\r\nThere are two types of SEPs:\r\n* data model -- a proposal to change or expand the SBOL data model\r\n* process -- a proposal of how to improve SBOL governance or management\r\n\r\n### 3.2    SEP Status\r\n\r\nEvery 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”.\r\n\r\n### 3.3 Document Layout\r\n\r\nAn 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 \"\\[ \\]\"):\r\n\r\n1. Preamble\r\n  * SEP number (assigned by editor, leave empty or XXX)\r\n  * descriptive title (limited to a maximum of 44 characters)\r\n  * names for each author\r\n  * created (date)\r\n  * Type of SEP (data model | process; process = SBOL organization or “governing rule”)\r\n  * \\[SBOL version\\] (version to which change should be introduced; if type == data model)\r\n  * \\[Replaces\\] (SEP number, only if this SEP is Final/Accepted and replaces another one)\r\n  * Status (Draft | Accepted | Rejected | Withdrawn | Deferred | Final | Active)\r\n \r\n2. Abstract -- a (very) short (~200 words, at most) summary of the proposed change or enhancement. \r\n\r\n3. 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.\r\n\r\n4. Specification -- 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).\r\n\r\n5. 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. \r\n\r\n6. 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.\r\n\r\n7. Discussion -- Summarize any relevant discussion, in particular counter-arguments brought up.\r\n\r\nReferences 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.\r\n\r\n### 3.4 Auxiliary Files\r\n\r\nSEPs 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.\r\n\r\n\r\n4. Example or Use Case <a name='example'></a>\r\n-------------------------------\r\n\r\nSEP 1 serves as first example of a SEP and the SEP adoption process.\r\n\r\n\r\n5. Discussion <a name='discussion'></a>\r\n-----------------\r\n\r\n### 5.1 current versus new issue tracker \r\n\r\nThis 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:\r\n\r\n* create a dedicated repo / issue tracker only for SEPs\r\n* 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\r\n* prescription of an official proposal template -- promoting minimal documentation standards\r\n* formalized and transparent process of decision making\r\n\r\nCompared 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.\r\n\r\nA 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.\r\n\r\n### 5.2 Filtering by editors\r\n\r\nIn 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.\r\n\r\n### 5.3 Should we reserve the first 10 or 20 SEP numbers for important SBOL government rules?\r\n\r\nIn 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.\r\n\r\nReferences <a name='references'></a>\r\n----------------\r\n\r\n[SBOL]: http://sbolstandard.org\r\n[1]: https://www.python.org/dev/peps/pep-0001\r\n\r\nCopyright <a name='copyright'></a>\r\n----------------\r\n<p xmlns:dct=\"http://purl.org/dc/terms/\" xmlns:vcard=\"http://www.w3.org/2001/vcard-rdf/3.0#\">\r\n  <a rel=\"license\"\r\n     href=\"http://creativecommons.org/publicdomain/zero/1.0/\">\r\n    <img src=\"http://i.creativecommons.org/p/zero/1.0/88x31.png\" style=\"border-style: none;\" alt=\"CC0\" />\r\n  </a>\r\n  <br />\r\n  To the extent possible under law,\r\n  <a rel=\"dct:publisher\"\r\n     href=\"sbolstandard.org\">\r\n    <span property=\"dct:title\">SBOL developers</span></a>\r\n  has waived all copyright and related or neighboring rights to\r\n  <span property=\"dct:title\">SEP 001</span>.\r\nThis work is published from:\r\n<span property=\"vcard:Country\" datatype=\"dct:ISO3166\"\r\n      content=\"US\" about=\"sbolstandard.org\">\r\n  United States</span>.\r\n</p>\r\n"},"comment":{"url":"https://api.github.com/repos/SynBioDex/SEPs/issues/comments/148481444","html_url":"https://github.com/SynBioDex/SEPs/issues/1#issuecomment-148481444","issue_url":"https://api.github.com/repos/SynBioDex/SEPs/issues/1","id":148481444,"user":{"login":"mgaldzic","id":406285,"avatar_url":"https://avatars.githubusercontent.com/u/406285?v=3","gravatar_id":"","url":"https://api.github.com/users/mgaldzic","html_url":"https://github.com/mgaldzic","followers_url":"https://api.github.com/users/mgaldzic/followers","following_url":"https://api.github.com/users/mgaldzic/following{/other_user}","gists_url":"https://api.github.com/users/mgaldzic/gists{/gist_id}","starred_url":"https://api.github.com/users/mgaldzic/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mgaldzic/subscriptions","organizations_url":"https://api.github.com/users/mgaldzic/orgs","repos_url":"https://api.github.com/users/mgaldzic/repos","events_url":"https://api.github.com/users/mgaldzic/events{/privacy}","received_events_url":"https://api.github.com/users/mgaldzic/received_events","type":"User","site_admin":false},"created_at":"2015-10-15T18:29:31Z","updated_at":"2015-10-15T18:29:31Z","body":"I like the two author rule as it means that you've had to talk to someone\nelse before positing it. However given that the gate to SEP positing is\nscreened via the editors... I do not see a reason for it. I would prefer to\nsee a responsible Editor listed and contributors acknowledged. For example\nsomething like: http://www.w3.org/TR/2013/NOTE-prov-primer-20130430/ Much\nlike with the W3C documents, sometimes it just editors.\n\nOn Thu, Oct 15, 2015 at 11:14 AM Raik Grünberg <notifications@github.com>\nwrote:\n\n> I am not sure about the two-author requirement. E.g. we currently only\n> have a single author on SEP #3\n> <https://github.com/SynBioDex/SEPs/issues/3> and nobody seems to be\n> concerned by that. Besides, in the python world, there are many\n> single-author PEPs.\n>\n> —\n> Reply to this email directly or view it on GitHub\n> <https://github.com/SynBioDex/SEPs/issues/1#issuecomment-148477340>.\n>\n"}}