New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SEP V006: No Glyph Assigned #11

Open
jakebeal opened this Issue Sep 14, 2017 · 19 comments

Comments

Projects
None yet
4 participants
@jakebeal
Contributor

jakebeal commented Sep 14, 2017

SEP V006: No Glyph Assigned

SEP
Authors Jacob Beal (jakebeal@ieee.org), Chris Myers
Editor
Type Specification
SBOL Visual Version 1.1
Status Draft
Created 14-Sep-2017
Last modified Never

Abstract

We need a way of distinguishing a Composite object (SO:0000804 Engineered Region) from a No Glyph Assigned object (i.e., any SO term that is not covered by any glyph besides the root Sequence Feature).

Table of Contents

1. Rationale

Two cases that currently do not have a clear way of visually distinguishing them are:

  • "No Glyph Assigned": Constructs with a well-defined and interesting type that happens to not be covered by any of the current glyphs. Here, we want people to recognize that the part is well understood, just outside the current vocabulary. We also want them to make new glyph proposals.
  • "Composite": Potentially complex designs composing multiple parts. Here we want to have people recognize that there is more detail available.

Here we focus on distinguishing No Glyph Assigned, which is intended for constructs with a defined specific role that happens to not yet be covered by available approved glyphs (other than the root "Sequence Feature"). It is more likely to appear in machine-generated diagrams than in human-generated diagrams, since humans are likely to invent and use their own glyph for the purpose.

2. Specification

The "User Defined" glyph has been split into three new glyphs: "Unspecified", "No Glyph Assigned", and "Composite". We have not yet, however, defined a glyph for "No Glyph Assigned"

A number of proposals have been made, from which we need to pick one to be RECOMMENDED for each and may choose to pick others as alternatives. The proposal is:

  • When a part has no assigned glyph it is RECOMMENDED that a user provide their own glyph. The user is also encouraged to submit the new glyph for possible adoption into the SBOLv standard.

  • An alternative is brackets, suggesting information that needs to be filled in:

glyph specification

As a best practice, it is suggested that the name of the term be put in between the brackets.

3. Examples

No Glyph Assigned is intended to be used for any Component that is not covered by other SBOL Visual glyphs.
For example, at present there is no glyph recommended for representing a transposon.

4. Backwards Compatibility

The "User Defined" rectangle will remain as a RECOMMENDED or alternative glyph for No Glyph Assigned.

5. Discussion

Alternatives currently without support:

  • Keep the "User Defined" rectangle as RECOMMENDED, a plain rectangle suggesting a blank slate to be written upon:

glyph specification

Alternate stylings of this rectangle might be preferred by users and tools:

  • A tall thin rectangle, which some fonts use as an alternative "replacement character":

    glyph specification

  • A dashed line rectangle, implying something is missing:

    glyph specification

Note that the User Defined rectangle causes No Glyph Assigned to conflict with Composite. We might correct this, however, by allowing the rectangle to be used only as part of a base glyph in composite, and withdrawing its use as an alternative for that glyph. Its use in Composite would then be distinguished by inclusion of the secondary backbone, e.g.,:

glyph specification

References

Copyright

CC0
To the extent possible under law, SBOL developers has waived all copyright and related or neighboring rights to SEP V006. This work is published from: United States.

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 14, 2017

Contributor

My personal preference is removing the rectangle glyph from "Composite", then having No Glyph Assigned recommend making your own, with rectangle as an alternative.

Contributor

jakebeal commented Sep 14, 2017

My personal preference is removing the rectangle glyph from "Composite", then having No Glyph Assigned recommend making your own, with rectangle as an alternative.

@swapnilb

This comment has been minimized.

Show comment
Hide comment
@swapnilb

swapnilb Sep 14, 2017

I propose that we remove the strange picture from the SEP as it adds close to nothing to the discussion.

swapnilb commented Sep 14, 2017

I propose that we remove the strange picture from the SEP as it adds close to nothing to the discussion.

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 14, 2017

Contributor

@swapnilb Alas, no matter how funny it is to me, I think you're right that "On Beyond Zebra" has no place in a formal document.

I have also updated to reflect the mailing list discussion leading to a suggestion of brackets.

Contributor

jakebeal commented Sep 14, 2017

@swapnilb Alas, no matter how funny it is to me, I think you're right that "On Beyond Zebra" has no place in a formal document.

I have also updated to reflect the mailing list discussion leading to a suggestion of brackets.

@cjmyers

This comment has been minimized.

Show comment
Hide comment
@cjmyers

cjmyers Sep 17, 2017

Do we need a separate SEP to make the rectangle the glyph for Engineered Region, or could that be part of this one?

cjmyers commented Sep 17, 2017

Do we need a separate SEP to make the rectangle the glyph for Engineered Region, or could that be part of this one?

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 18, 2017

Contributor

@cjmyers No need: we already voted that in as part of the "backward compatibility" portion of SEP V003. See: https://github.com/SynBioDex/SBOLv-realizations/tree/develop/Glyphs/composite

Contributor

jakebeal commented Sep 18, 2017

@cjmyers No need: we already voted that in as part of the "backward compatibility" portion of SEP V003. See: https://github.com/SynBioDex/SBOLv-realizations/tree/develop/Glyphs/composite

@jakebeal jakebeal added this to the SBOLv 1.1 milestone Sep 25, 2017

@JS3xton

This comment has been minimized.

Show comment
Hide comment
@JS3xton

JS3xton Sep 27, 2017

Now that I've caught up on some of the discussion of this topic (https://groups.google.com/forum/#!topic/sbol-dev/YRoyNULWu4o), and at the risk of beating a dead horse, I'm going to re-raise what @cjmyers said (and I'm going to try to be overly verbose, because I think the distinction may be subtle): I think we need another SEP to introduce an Engineered Region glyph.

My understanding of the current state:

  • The SBOL Visual 1.0 specification describes the "User Defined" glyph (a rectangle; no associated SO terms).
  • The "User Defined" glyph (as described by the SBOL Visual 1.0 specification) will be done away with in favor of the "Unspecified" glyph, the "No Glyph Assigned" glyph, and the "Composite" glyph (see SEP V003 and this SEP).

What I would still like to see change:

  • Introduction of a new "Engineered Region" glyph.
  • Disassociation of SO:0000804 from the "Composite" glyph
  • Association of SO:0000804 with the new "Engineered Region" glyph
  • Specification of a glyph for the "Engineered Region" glyph (@cjmyers has advocated strongly for the rectangle, which now has my support)
  • Removal of the rectangle as an alternative for the "Composite" glyph (and probably removal of rectangle as an alternative for the "Unspecified" glyph)

To underscore:

  • I think the "Composite" glyph and the SO:0000804 ("engineered_region") Sequence Ontology term are confusingly conflated at present; I believe @cjmyers has sufficiently motivated them as being distinct concepts here.
  • @cjmyers has also convincingly argued that it is detrimentally unclear to illustrate engineered regions with the "No Glyph Assigned" glyph here.
  • If the changes I proposed were made, the rectangle would only represent the "Engineered Region" glyph (screw backwards compatibility...).

The picture I drew to organize my thoughts...:

JS3xton commented Sep 27, 2017

Now that I've caught up on some of the discussion of this topic (https://groups.google.com/forum/#!topic/sbol-dev/YRoyNULWu4o), and at the risk of beating a dead horse, I'm going to re-raise what @cjmyers said (and I'm going to try to be overly verbose, because I think the distinction may be subtle): I think we need another SEP to introduce an Engineered Region glyph.

My understanding of the current state:

  • The SBOL Visual 1.0 specification describes the "User Defined" glyph (a rectangle; no associated SO terms).
  • The "User Defined" glyph (as described by the SBOL Visual 1.0 specification) will be done away with in favor of the "Unspecified" glyph, the "No Glyph Assigned" glyph, and the "Composite" glyph (see SEP V003 and this SEP).

What I would still like to see change:

  • Introduction of a new "Engineered Region" glyph.
  • Disassociation of SO:0000804 from the "Composite" glyph
  • Association of SO:0000804 with the new "Engineered Region" glyph
  • Specification of a glyph for the "Engineered Region" glyph (@cjmyers has advocated strongly for the rectangle, which now has my support)
  • Removal of the rectangle as an alternative for the "Composite" glyph (and probably removal of rectangle as an alternative for the "Unspecified" glyph)

To underscore:

  • I think the "Composite" glyph and the SO:0000804 ("engineered_region") Sequence Ontology term are confusingly conflated at present; I believe @cjmyers has sufficiently motivated them as being distinct concepts here.
  • @cjmyers has also convincingly argued that it is detrimentally unclear to illustrate engineered regions with the "No Glyph Assigned" glyph here.
  • If the changes I proposed were made, the rectangle would only represent the "Engineered Region" glyph (screw backwards compatibility...).

The picture I drew to organize my thoughts...:

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 27, 2017

Contributor

@cjmyers Your thoughts on @JS3xton proposal? I could potentially be persuaded to either keep them together or split them, and I know you have strong opinions based on your experiences with SynBioHub.

Contributor

jakebeal commented Sep 27, 2017

@cjmyers Your thoughts on @JS3xton proposal? I could potentially be persuaded to either keep them together or split them, and I know you have strong opinions based on your experiences with SynBioHub.

@cjmyers

This comment has been minimized.

Show comment
Hide comment
@cjmyers

cjmyers Sep 27, 2017

cjmyers commented Sep 27, 2017

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 27, 2017

Contributor

As I understand it, there are really two key changes under consideration here:

  1. Removal of backward-compatible "Rectangle" as an alternate for "Unspecified"
  2. Division of "Engineered Region" from "Composite."

I would strongly oppose the first for SBOLv 1.1, but would be willing to consider it for SBOLv 2.0.

For the second, my key question is this: are there circumstances in which SO:0000804 is not a reasonable description of a Composite? If so, then they clearly should be divided; if not, it will take more consideration.

Finally, To answer @cjmyers question about SEPs --- these are definitely not changes already supported by the current SEPs; I believe @JS3xton has summarized the current state correctly (except for the ambiguous position of the backbone on some of the glyphs).

Contributor

jakebeal commented Sep 27, 2017

As I understand it, there are really two key changes under consideration here:

  1. Removal of backward-compatible "Rectangle" as an alternate for "Unspecified"
  2. Division of "Engineered Region" from "Composite."

I would strongly oppose the first for SBOLv 1.1, but would be willing to consider it for SBOLv 2.0.

For the second, my key question is this: are there circumstances in which SO:0000804 is not a reasonable description of a Composite? If so, then they clearly should be divided; if not, it will take more consideration.

Finally, To answer @cjmyers question about SEPs --- these are definitely not changes already supported by the current SEPs; I believe @JS3xton has summarized the current state correctly (except for the ambiguous position of the backbone on some of the glyphs).

@cjmyers

This comment has been minimized.

Show comment
Hide comment
@cjmyers

cjmyers Sep 27, 2017

cjmyers commented Sep 27, 2017

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 27, 2017

Contributor

A technical note: it can be both a terminator and an engineered region, because the rule is only a "best practice" recommendation.

That said, I do find that a compelling case, and think that it would make sense to launch an SEP to make the split that @JS3xton suggests.

Contributor

jakebeal commented Sep 27, 2017

A technical note: it can be both a terminator and an engineered region, because the rule is only a "best practice" recommendation.

That said, I do find that a compelling case, and think that it would make sense to launch an SEP to make the split that @JS3xton suggests.

@JS3xton

This comment has been minimized.

Show comment
Hide comment
@JS3xton

JS3xton Sep 29, 2017

@jakebeal

I would strongly oppose the first [Removal of backward-compatible "Rectangle" as an alternate for "Unspecified"] for SBOLv 1.1, but would be willing to consider it for SBOLv 2.0.

@cjmyers

Ok to leave Rectangle for Unspecified for 1.1 but as deprecated usage (i.e., strongly discouraged).

Hmmm, I guess I'm a little confused on how SEP V003, this SEP, and a hypothetical "Engineered Region" glyph SEP will/would be realized, how that realization informs which specification (SBOLv 1.1 vs. SBOLv 2.0) is appropriate (I have the Semantic Versioning system in mind), and what exactly "backwards compatible" means in the context of SBOL Visual.

For example, one way I could see this playing out is that the introduction of the "Engineered Region" glyph is considered a backwards-compatible renaming (or "refining of the definition") of the "User Defined" glyph (which includes an association of that renamed glyph with the SO:0000804 Sequence Ontology term). It follows that the "Composite" glyph, the "No Glyph Assigned" glyph, and the "Unspecified' glyph are all simply treated as new glyphs (relative to SBOLv 1.0; no backwards compatibility constraints) and all of these changes make it into the SBOLv 1.1 specification (this SEP would have to supersede SEP V003 in removing the rectangle as a valid alternative for the "Composite" glyph and the "Unspecified" glyph, though).

Alternatively, if I am more strict, I might claim that any changes that render the "User Defined" glyph not exactly as it is currently specified in the SBOLv 1.0 specification are considered not backwards compatible and must go in a major version bump (e.g. SBOLv 2.0). Under such an interpretation, perhaps the "Unspecified" glyph (without the rectangle alternative) the "No Glyph Assigned" glyph, and the "Composite" glyph (without the rectangle alternative) could be introduced in SBOLv 1.1 (the "User Defined" rectangle glyph would still exist, though! It could perhaps be deprecated at this point?), and the "User Defined" glyph could be retired and the "Engineered Region" glyph could recapture the rectangle glyph and the SO:0000804 Sequence Ontology term in the SBOLv 2.0 specification.

It might be cleaner to just hold all of these "User Defined" glyph derivatives for the major version bump (SBOLv 2.0), though?

¯\_(ツ)_/¯

JS3xton commented Sep 29, 2017

@jakebeal

I would strongly oppose the first [Removal of backward-compatible "Rectangle" as an alternate for "Unspecified"] for SBOLv 1.1, but would be willing to consider it for SBOLv 2.0.

@cjmyers

Ok to leave Rectangle for Unspecified for 1.1 but as deprecated usage (i.e., strongly discouraged).

Hmmm, I guess I'm a little confused on how SEP V003, this SEP, and a hypothetical "Engineered Region" glyph SEP will/would be realized, how that realization informs which specification (SBOLv 1.1 vs. SBOLv 2.0) is appropriate (I have the Semantic Versioning system in mind), and what exactly "backwards compatible" means in the context of SBOL Visual.

For example, one way I could see this playing out is that the introduction of the "Engineered Region" glyph is considered a backwards-compatible renaming (or "refining of the definition") of the "User Defined" glyph (which includes an association of that renamed glyph with the SO:0000804 Sequence Ontology term). It follows that the "Composite" glyph, the "No Glyph Assigned" glyph, and the "Unspecified' glyph are all simply treated as new glyphs (relative to SBOLv 1.0; no backwards compatibility constraints) and all of these changes make it into the SBOLv 1.1 specification (this SEP would have to supersede SEP V003 in removing the rectangle as a valid alternative for the "Composite" glyph and the "Unspecified" glyph, though).

Alternatively, if I am more strict, I might claim that any changes that render the "User Defined" glyph not exactly as it is currently specified in the SBOLv 1.0 specification are considered not backwards compatible and must go in a major version bump (e.g. SBOLv 2.0). Under such an interpretation, perhaps the "Unspecified" glyph (without the rectangle alternative) the "No Glyph Assigned" glyph, and the "Composite" glyph (without the rectangle alternative) could be introduced in SBOLv 1.1 (the "User Defined" rectangle glyph would still exist, though! It could perhaps be deprecated at this point?), and the "User Defined" glyph could be retired and the "Engineered Region" glyph could recapture the rectangle glyph and the SO:0000804 Sequence Ontology term in the SBOLv 2.0 specification.

It might be cleaner to just hold all of these "User Defined" glyph derivatives for the major version bump (SBOLv 2.0), though?

¯\_(ツ)_/¯

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 29, 2017

Contributor

@JS3xton The key element in backward compatibility is the linkage with the Sequence Ontology terms:

  • Although it is RECOMMENDED that one use the most specific glyph available, it is still acceptable to use less specific glyphs.
  • SO:0000110 Sequence Feature is a root term in Sequence Ontology, and thus its glyph can be substituted for any glyph.

Currently, there are a bunch of diagrams and software tools out there that use Rectangle to mean a whole bunch of different things, consistent with the SBOL Visual 1.0 catch-all "User Defined." As long as we allow Rectangle to be an acceptable alternate glyph for SO:0000110, all of these diagrams remain valid. Once we remove that usage, then those diagrams become incompatible whenever they meant something not covered by SO:0000804.

That is why I like keeping Rectangle in SBOL Visual 1.1 as a deprecated alternative for Unspecified (since that is the home of SO:0000110), then dropping it when we move to SBOL Visual 2.0.

Contributor

jakebeal commented Sep 29, 2017

@JS3xton The key element in backward compatibility is the linkage with the Sequence Ontology terms:

  • Although it is RECOMMENDED that one use the most specific glyph available, it is still acceptable to use less specific glyphs.
  • SO:0000110 Sequence Feature is a root term in Sequence Ontology, and thus its glyph can be substituted for any glyph.

Currently, there are a bunch of diagrams and software tools out there that use Rectangle to mean a whole bunch of different things, consistent with the SBOL Visual 1.0 catch-all "User Defined." As long as we allow Rectangle to be an acceptable alternate glyph for SO:0000110, all of these diagrams remain valid. Once we remove that usage, then those diagrams become incompatible whenever they meant something not covered by SO:0000804.

That is why I like keeping Rectangle in SBOL Visual 1.1 as a deprecated alternative for Unspecified (since that is the home of SO:0000110), then dropping it when we move to SBOL Visual 2.0.

@cjmyers

This comment has been minimized.

Show comment
Hide comment
@cjmyers

cjmyers Sep 29, 2017

cjmyers commented Sep 29, 2017

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Sep 29, 2017

Contributor

If we don't break backward compatibility, Rectangle will still be deprecated, and that's at least some motivator...

Contributor

jakebeal commented Sep 29, 2017

If we don't break backward compatibility, Rectangle will still be deprecated, and that's at least some motivator...

@JS3xton

This comment has been minimized.

Show comment
Hide comment
@JS3xton

JS3xton Sep 29, 2017

Selected Responses

@jakebeal:

As long as we allow Rectangle to be an acceptable alternate glyph for SO:0000110, all of these diagrams remain valid.

I don't like this statement, but I'm struggling to determine exactly why. What I will say: SO:0000110 ("sequence_feature") should not be acknowledge by the standards until the "Unspecified" glyph is introduced (without the rectangle alternative, in my opinion), and I advocate below for that not happening until SBOLv 2.0. Under this scenario, the rectangle glyph will never have been an explicitly acceptable alternative for SO:0000110 (it may have been implicitly acceptable via the "User Defined" glyph, though, up until but not including SBOLv 2.0).

@jakebeal:

Once we remove that usage, then those diagrams become incompatible whenever they meant something not covered by SO:0000804.

  • I don't understand why SO:0000804 ("engineered_region") is entering the conversation. SO:0000804 is unaffiliated with any term in SBOLv 1.0, and may be unaffiliated with any term in SBOLv 1.1 (if, indeed, it gets disassociated from the "Composite" glyph, which I advocate for introduction in SBOLv 1.1, and is associated with a hypothetical "Engineered Region" glyph, which I advocate for introduction in SBOLv 2.0).

  • I also agree with @cjmyers:

    If you have a software that uses rectangle as user defined, then it is simply a software that produces SBOLv 1.0 diagrams.

    A major version bump (e.g. 1.* to 2.0) is not required to be compatible; a minor version bump (e.g. 1.0 to 1.1), on the other hand, should be backwards compatible. So use of the rectangle glyph to describe something other than an engineered region is a valid use of that glyph in a SBOLv 1.0- (or SBOLv 1.1-)sanctioned diagram. Combining that use case (rectangle glyph describing something other than an engineered region) with other features introduced in SBOLv 2.0 would be invalid, though.

@jakebeal:

That is why I like keeping Rectangle in SBOL Visual 1.1 as a deprecated alternative for Unspecified (since that is the home of SO:0000110), then dropping it when we move to SBOL Visual 2.0.

It seems strange to me to deprecate a new feature (the "Unspecified" glyph) that you are also simultaneously introducing, so I don't like that interpretation. I think the "User Defined" glyph should be considered deprecated, if anything.

It's also unclear to me what it means to "deprecate" a SBOL Visual glyph. Clarification there would help me, ideally with a prototypical example. I think this particular case is also complicated by the fact that the glyph in question is hypothetically being recycled (not simply retired and removed from sanctioned use).

@jakebeal:

If we don't break backward compatibility, Rectangle will still be deprecated, and that's at least some motivator...

I don't understand what you mean by this. (sry 😆) Can you re-express this and be more verbose if it's still a worthwhile point to make?

My Preferences

  • The "Composite" glyph (without the rectangle alternative or the SO:0000804 ("engineered_region") association) and the "Omitted Detail" glyph are useful and sufficiently orthogonal to the rectangle glyph drama that they should be introduced in SBOLv 1.1.
  • The "User Defined" glyph should not be retired until (at least) SBOLv 2.0, and a hypothetical "Engineered Region" glyph that recycles the rectangle glyph should not be introduced until (at least) SBOLv 2.0.
  • For clarity, I think the "No Glyph Assigned" glyph and the "Unspecified" glyph (without the rectangle alternative) should be introduced at the same time that the "User Defined" glyph is retired and a hypothetical "Engineered Region" glyph that recycles the rectangle glyph is introduced (e.g. SBOLv 2.0). That way we replace the more general "User Defined" glyph with all of its more precise derivatives at the same time.
    • I originally thought the "No Glyph Assigned" glyph and the "Unspecified" glyph (without the rectangle alternative) could coexist with the "User Defined" glyph (i.e. be introduced in SBOLv 1.1), but I think it becomes really confusing which glyph should be used in some scenarios given how broad the "User Defined" glyph is in contrast to how specific the concepts that the "No Glyph Assigned" glyph and the "Unspecified" glyph describe are.

JS3xton commented Sep 29, 2017

Selected Responses

@jakebeal:

As long as we allow Rectangle to be an acceptable alternate glyph for SO:0000110, all of these diagrams remain valid.

I don't like this statement, but I'm struggling to determine exactly why. What I will say: SO:0000110 ("sequence_feature") should not be acknowledge by the standards until the "Unspecified" glyph is introduced (without the rectangle alternative, in my opinion), and I advocate below for that not happening until SBOLv 2.0. Under this scenario, the rectangle glyph will never have been an explicitly acceptable alternative for SO:0000110 (it may have been implicitly acceptable via the "User Defined" glyph, though, up until but not including SBOLv 2.0).

@jakebeal:

Once we remove that usage, then those diagrams become incompatible whenever they meant something not covered by SO:0000804.

  • I don't understand why SO:0000804 ("engineered_region") is entering the conversation. SO:0000804 is unaffiliated with any term in SBOLv 1.0, and may be unaffiliated with any term in SBOLv 1.1 (if, indeed, it gets disassociated from the "Composite" glyph, which I advocate for introduction in SBOLv 1.1, and is associated with a hypothetical "Engineered Region" glyph, which I advocate for introduction in SBOLv 2.0).

  • I also agree with @cjmyers:

    If you have a software that uses rectangle as user defined, then it is simply a software that produces SBOLv 1.0 diagrams.

    A major version bump (e.g. 1.* to 2.0) is not required to be compatible; a minor version bump (e.g. 1.0 to 1.1), on the other hand, should be backwards compatible. So use of the rectangle glyph to describe something other than an engineered region is a valid use of that glyph in a SBOLv 1.0- (or SBOLv 1.1-)sanctioned diagram. Combining that use case (rectangle glyph describing something other than an engineered region) with other features introduced in SBOLv 2.0 would be invalid, though.

@jakebeal:

That is why I like keeping Rectangle in SBOL Visual 1.1 as a deprecated alternative for Unspecified (since that is the home of SO:0000110), then dropping it when we move to SBOL Visual 2.0.

It seems strange to me to deprecate a new feature (the "Unspecified" glyph) that you are also simultaneously introducing, so I don't like that interpretation. I think the "User Defined" glyph should be considered deprecated, if anything.

It's also unclear to me what it means to "deprecate" a SBOL Visual glyph. Clarification there would help me, ideally with a prototypical example. I think this particular case is also complicated by the fact that the glyph in question is hypothetically being recycled (not simply retired and removed from sanctioned use).

@jakebeal:

If we don't break backward compatibility, Rectangle will still be deprecated, and that's at least some motivator...

I don't understand what you mean by this. (sry 😆) Can you re-express this and be more verbose if it's still a worthwhile point to make?

My Preferences

  • The "Composite" glyph (without the rectangle alternative or the SO:0000804 ("engineered_region") association) and the "Omitted Detail" glyph are useful and sufficiently orthogonal to the rectangle glyph drama that they should be introduced in SBOLv 1.1.
  • The "User Defined" glyph should not be retired until (at least) SBOLv 2.0, and a hypothetical "Engineered Region" glyph that recycles the rectangle glyph should not be introduced until (at least) SBOLv 2.0.
  • For clarity, I think the "No Glyph Assigned" glyph and the "Unspecified" glyph (without the rectangle alternative) should be introduced at the same time that the "User Defined" glyph is retired and a hypothetical "Engineered Region" glyph that recycles the rectangle glyph is introduced (e.g. SBOLv 2.0). That way we replace the more general "User Defined" glyph with all of its more precise derivatives at the same time.
    • I originally thought the "No Glyph Assigned" glyph and the "Unspecified" glyph (without the rectangle alternative) could coexist with the "User Defined" glyph (i.e. be introduced in SBOLv 1.1), but I think it becomes really confusing which glyph should be used in some scenarios given how broad the "User Defined" glyph is in contrast to how specific the concepts that the "No Glyph Assigned" glyph and the "Unspecified" glyph describe are.
@cjmyers

This comment has been minimized.

Show comment
Hide comment
@cjmyers

cjmyers Sep 30, 2017

cjmyers commented Sep 30, 2017

@JS3xton

This comment has been minimized.

Show comment
Hide comment
@JS3xton

JS3xton Oct 1, 2017

At present, I support going straight to SBOLv 2.0.

In my software engineering endeavors, I've become familiar with and embraced this Git Branching Model, which discusses a relevant point (in my opinion) when it describes Release Branches:

It is exactly at the start of a release branch that the upcoming release gets assigned a version number—not any earlier. Up until that moment, the develop branch reflected changes for the “next release”, but it is unclear whether that “next release” will eventually become 0.3 or 1.0, until the release branch is started. That decision is made on the start of the release branch and is carried out by the project’s rules on version number bumping.

(if we were going to be super explicit with the analogy, we might even have a "Develop" Milestone, and only spawn versioned Milestones when there's consensus from the community that it's time for a new release)

Regarding version number bumping, I've come to embrace the versioning philosophy described by Semantic Versioning. Some relevant excerpts:

  1. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.
  1. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

They also talk about excessive major version bumps in the FAQ here.

I will be the first to admit that this is just one system for managing version numbers for a project, which happens to have been useful to me in other software engineering contexts, but may not be appropriate for SBOL Visual. If we were to employ such a system, though, we should probably stop prematurely branding sets of enhancements with version numbers.

JS3xton commented Oct 1, 2017

At present, I support going straight to SBOLv 2.0.

In my software engineering endeavors, I've become familiar with and embraced this Git Branching Model, which discusses a relevant point (in my opinion) when it describes Release Branches:

It is exactly at the start of a release branch that the upcoming release gets assigned a version number—not any earlier. Up until that moment, the develop branch reflected changes for the “next release”, but it is unclear whether that “next release” will eventually become 0.3 or 1.0, until the release branch is started. That decision is made on the start of the release branch and is carried out by the project’s rules on version number bumping.

(if we were going to be super explicit with the analogy, we might even have a "Develop" Milestone, and only spawn versioned Milestones when there's consensus from the community that it's time for a new release)

Regarding version number bumping, I've come to embrace the versioning philosophy described by Semantic Versioning. Some relevant excerpts:

  1. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.
  1. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

They also talk about excessive major version bumps in the FAQ here.

I will be the first to admit that this is just one system for managing version numbers for a project, which happens to have been useful to me in other software engineering contexts, but may not be appropriate for SBOL Visual. If we were to employ such a system, though, we should probably stop prematurely branding sets of enhancements with version numbers.

@jakebeal jakebeal added Accepted and removed Draft labels Oct 5, 2017

@jakebeal

This comment has been minimized.

Show comment
Hide comment
@jakebeal

jakebeal Oct 7, 2017

Contributor

@JS3xton @cjmyers Per our discussion, I have opened SEP V009 for splitting Engineered Region from Composite.

Contributor

jakebeal commented Oct 7, 2017

@JS3xton @cjmyers Per our discussion, I have opened SEP V009 for splitting Engineered Region from Composite.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment