Permalink
Browse files

SEP 029 -- Update to issue procedure for SEPs (#63)

[SEP 001](#1) defined the procedure for managing SEPs.  This procedure currently mandates that all SEPs remain "open" on the issue tracker so that they are all visible by default. This SEP proposes that this requirement is changed so that SEPs issues can be closed when action is no longer required. This SEP also clarifies that the definitive text for an SEP is in the repository and not the issue tracker, solving the problem of unnecessary copy and pasting between the two.

https://github.com/udp/SEPs/blob/master/sep_029.md
  • Loading branch information...
udp authored and palchicz committed Dec 30, 2018
1 parent b8c77f1 commit 17bb230c5313c415df935b1a901de6bb2c346a06
Showing with 75 additions and 0 deletions.
  1. +75 −0 sep_029.md
@@ -0,0 +1,75 @@
SEP 029 -- Update to issue procedure for SEPs
===================================

SEP | 029
----------------------|--------------
**Title** | Update to issue procedure for SEPs
**Authors** | James Alastair McLaughlin (j.a.mclaughlin@ncl.ac.uk)
**Editor** |
**Type** | Procedure
**Replaces** |
**Status** | Draft
**Created** | 17-Oct-2018
**Last modified** | 17-Oct-2018

## Abstract

[SEP 001](https://github.com/SynBioDex/SEPs/issues/1) defined the procedure for managing SEPs. This procedure currently mandates that all SEPs remain "open" on the issue tracker so that they are all visible by default. This SEP proposes that this requirement is changed so that SEPs issues can be closed when action is no longer required. This SEP also clarifies that the definitive text for an SEP is in the repository and not the issue tracker, solving the problem of unnecessary copy and pasting between the two. Finally, this SEP also recommends that SEPs concerning the specification are accompanied by a pull request to the [SBOL specification repository](https://github.com/SynBioDex/SBOL-specification).

## Motivation

It is generally accepted (citation needed) when using GitHub for software development that an open issue is something that requires attention, and when attention is no longer required, the issue can be closed. As we are repurposing the GitHub issue tracker for keeping track of SEPs, it would therefore be logical that the issues SEPs that no longer require editorial attention (e.g. revoked, or merged into spec) can be closed.

Moreover, in the current system, the text of SEPs is duplicated; it is usually copied once for the markdown file contained in the repository itself, and once for the issue. In this SEP we recommend that the text of SEPs exist only in the repository. SEPs can then remain permanently in the repository for posterity, while their issues can eventually be closed by the editors. Using the repository as the definitive resource rather than the issue tracker is important for openness: issues are only accessible by the proprietary GitHub API, whereas the repository itself can be cloned or moved elsewhere. The current system also suggests that issue numbers correspond to SEP numbers, which has not been the case in practice.

Finally, there is a latency issue between the acceptance of SEPs and their merging into the SBOL specification. This SEP attempts to mitigate this by recommending that any SEP concerning the specification is accompanied by a pull request to the SBOL specification repository.

## Specification

The following text of SEP 001 under "2.5 Decision":

> 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.
Is superceded by the following:

> SEPs remain "Open" on the issue tracker until they no longer require attention; i.e., have been either accepted and merged into the specification, rejected, or revoked.
The following text under "2.2 SEP Submission":

> 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.
Is superceded by the following:

> If approved, an editor will merge the pull request for the SEP into the dedicated SEPs repository on github, for which only SBOL editors have write-access.
After the steps for forking and opening a pull request to the SEPs repository in "2.2 SEP Submission", the following text is added:

> If the SEP concerns the SBOL specification, it is recommended that a corresponding pull request is also opened in the [SBOL specification repository](https://github.com/SynBioDex/SBOL-specification). This ensures that if the SEP is accepted, it can be swiftly merged into the specification.


## Discussion

It should be noted that closed issues are not deleted and are always accessible and searchable through the same user interface as open issues.

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 002</span>.
This work is published from:
<span property="vcard:Country" datatype="dct:ISO3166"
content="US" about="sbolstandard.org">
United Kingdom</span>.
</p>

0 comments on commit 17bb230

Please sign in to comment.