Re: [Obo-discuss] release versioning best practice conventions

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

The public version of principle 4 (the page you linked) shows the 
original text. The Editorial Working Group of the OBO Foundry has been 
(very slowly) going through these to provide more guidance. Such has 
been done for principle 4, but the new text has not yet been vetted. 
Nonetheless, in light of this discussion, I reproduce what we have so 
far in hopes that a final decision can be made.:

Name: versioning

Summary:
The ontology provider has documented procedures for versioning the 
ontology, and different versions of ontology are marked, stored, and 
officially released.

Purpose:
Ontologies are developed and refined over time. Similarly, they are 
consumed at different points in time. The latter could lead to 
differences when comparing different sets of results. Accordingly, it 
becomes important to track precisely which version of an ontology has 
been used, and be able to retrieve past versions. Note that this applies 
only to those versions which have been officially released.

Recommendation:
Version identifiers can be of the form “YYYY-MM-DD” (that is, a date), 
or use a numbering system, but in any case each must associate with a 
distinct official release. The date versioning system is preferred, as 
it meshes with the OBO Foundry ID policy that also governs PURLs (see 
below).

Implementation:
Regardless of the versioning system chosen (see below), the PURL must 
use a date. In cases where there multiple releases on the same day, the 
PURL points to the newest, and the previous release stays in the same 
folder or a subfolder, named in such a way as to distinguish the 
releases. Ontology developers must maintain--and make publicly 
accessible into perpetuity--every official release. That is, the PURLs 
pointing to each version must resolve, even if the file was moved 
physically.

If terms are imported from an external ontology, the “IAO:imported from” 
annotation (see Principle 1) may specify a dated version of the ontology 
from which they are imported.

Examples:
For an OBO format ontology use the metadata tag:

data-version: 2015-03-31
data-version: 44.0

For an OWL format ontology, owl:versionInfo identifies the version and 
versionIRI identifies the resource:

<owl:versionInfo 
rdf:datatype="http://www.w3.org/2001/XMLSchema#string">2014-12-03</owl:versionInfo>
<owl:versionIRI 
rdf:resource="http://purl.obolibrary.org/obo/obi/2014-12-03/obi.owl"/>

===

An alternative proposal, again not yet vetted:

Purpose:
OBO projects share their ontologies using files in OWL or OBO format 
(see OBO Principle 2). Ontologies are expected to change over time as 
they are developed and refined (see OBO Principle 16 on maintenance). 
This will lead to a series of different files. Consumers of ontologies 
must be able to specify exactly which ontology files they used to encode 
their data or build their applications, and be able to retrieve 
unaltered copies of those files in perpetuity.

Recommendation:
OBO projects must publicly release official versions of their ontologies 
from time to time. Each official release must have one or more files in 
OWL or OBO format. Each official released must also have a unique 
version IRI that conforms to the OBO ID Policy. The version IRI of each 
official release is a Permanent URL (PURL), and the OBO project must 
ensure that the PURL of each official release continues to resolve to 
the files for that release, in perpetuity. If the files are moved, the 
PURL must be updated to resolve to the new location. Consumers can then 
use the version IRI to uniquely identify which official release of the 
ontology they used, and to retrieve unaltered copies of the file(s).

The content of official release files MUST NOT be changed. For example, 
if a bug is found in some official released file for some ontology, the 
bug MUST NOT be fixed by changing the file(s) for that official release. 
Instead the bug fixes should be included in a new official release, with 
new files, and consumers can switch to the new release.

All OBO purjects must also have a PURL that resolves to the current 
official release of their ontology.

===

Again, none of this is yet finalized, but I provide it to show where the 
discussion has led so far. I think one of the sticking points is that 
while the date versioning method was preferred by most, it fails to take 
into account the possibility that multiple versions can be released on a 
given date.

On 5/31/2017 10:47 AM, Hilmar Lapp wrote:
> Hi all,
>
> I’m wondering whether the OBO community has developed commonly followed
> conventions for versioning releases of ontologies.
>
> It seems that in the past one of the practices followed was to use the
> release date (such as in the format ‘YYYY-MM-DD’) as the release
> version, and consequently as a prefix in owl:versionIRI. I haven’t
> broadly surveyed the OBO ontologies yet to see whether that’s still
> broadly used or not.
>
> The OBO Foundry principle on the subject
> (http://www.obofoundry.org/principles/fp-004-versioning.html) is
> unfortunately rather unhelpful (it seems to say “anything goes as long
> as you can state it”).
>
> Whether or not the date-based YYYY-MM-DD is still the most commonly used
> convention, it strikes me as a poor choice (because – not without irony
> – it is bare of any semantics), and hence I’d like to move the
> ontologies I’m involved with (which have been using this convention) to
> a better one. In the software (including scientific software) realm,
> semantic versioning (http://semver.org) is being increasingly widely
> adopted, and as a result will likely be already familiar in some way or
> another to many people involved with ontology engineering. I’m wondering
> whether arguments for or against adopting semantic versioning have been
> discussed for OBO ontologies in the past.
>
> Obviously, OWL gives us the language to expressly assert compatibility
> semantics between different versions of an ontology, so one might ask
> why use or bother with a convention for release versions that leaves
> those semantics implicit and thus much more ambiguous and up to
> individual interpretation. For me, my response to that is that it’s not
> an either/or – version naming and expressly asserting compatibility
> semantics can, and IMHO should be complementary. The name of a version
> is primarily for communication between humans, not machines, and the
> precision in human communication matters too. At present, ontology
> versions used in publications, to the extent that I’m aware, are _at
> best_ cited by date. Not all dated release versions of all ontologies
> are archived for perpetuity (in fact most are not), and therefore after
> only a few years the ontology or ontologies used in such papers become
> not only essentially irreproducible, but also no notion can be recovered
> at all about the extent an archived version would or not be compatible
> with one used in the paper. This is dramatically different from software
> used in papers (setting aside the issue that authors frequently forget
> to include the version of a software tool they used).
>
> I’m curious about thoughts about this in the community, and am wondering
> what the OBO Foundry’s position is on developing a much stronger
> principle on release versioning.
>
>   -hilmar
>
> --
> Hilmar Lapp -:- lappland.io <http://lappland.io>
>
>
>
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>
>
>
> _______________________________________________
> Obo-discuss mailing list
> Obo...@li...
> https://lists.sourceforge.net/lists/listinfo/obo-discuss
>