Normative part of the website should be versioned

[gouttegd]

As we head towards SSSOM 1.1, the fact that the website is not versioned is going to pose a problem. In fact, I’d argue it already does.

We update the website on https://mapping-commons.github.io/sssom/ whenever we push anything to the master branch (through the deploy_documentation.yml workflow). As a result, the website always reflects the state of the latest development version of SSSOM (the tip of the master branch).

This may be fine for the documentation part of the website (the non-normative part). But for the normative part (the SSSOM specification itself), I believe this is problematic.

Right now, even though officially there is no other version of the SSSOM specification than the 1.0 version published in August 2024, the only available specification document describes slots and enumeration values that do not, in fact, belong to SSSOM 1.0 but that will instead be part of the upcoming SSSOM 1.1. Not only is that needlessly confusing, it also means that people have no easy way of getting the actual SSSOM 1.0 specification. They can only do that by going to the repository (not the website) and navigating to the SSSOM 1.0 tag – hardly a satisfying solution.

When SSSOM 1.1 will be released, then for a while the website will contain the accurate specification for the latest released version of the standard, but as soon as we will start updatig the master branch again (e.g. to add new slots for for a future 1.2 version), the same problem will happen again: the only available specification document will describe a work-in-progress and not the latest published version of the standard.

I believe the website, or at least the part of the website containing the actual specification, should be versioned.

That is, right now (before the SSSOM 1.1 release), it should contain two versions of the spec:

• the 1.0 version (frozen as it was in August 2024),
• and the development version (updated whenever the master branch is updated).

After the SSSOM 1.1 release, it should contain:

• the 1.0 version (still frozen in the state it was in August 2024),
• the 1.1 version (frozen in the state it was on the day the 1.1 version is released),
• and the development version (which for a while will actually be identical to 1.1, until development resumes towards 1.2).

And so on as we publish newer versions.

[gouttegd]

Somehow related to #119 , though I think “showing the model version the documentation relates to” is not enough.

[matentzn]

High interest, full agree.

[graybeal]

I’m not sure who the audience is for a dev version on the site, or even for the released version. I’d suggest if you’re going to show a version it should be the current release, that’s the typical practice in my experience. After all a dev will know how to access the dev versions on the repo, right?

That change should be pretty trivial. If you do that, I’m not sure ‘versioning the web site’ (by which I mean putting it into GitHub) is a useful thing. I might be misunderstanding what is meant there.

[matentzn]

@graybeal I think there are two issues here:

1. the raw state of the spec (spec as in - the fully manifested spec) not in version control. This means, regardless of any website to browse old versions, its a pain to really see what the spec was for version 1.0 if you and your organisation are still on 1.0.
2. Being able to look at older versions of SSSOM spec on the website. I think this is useful if you have a little version switcher up top; I agree with you that by default this is the current release (which is what most users will need), but for tool developers the development snapshot is the most important, so it would be good id they could browse that somehow painlessly.

[gouttegd]

I might be misunderstanding what is meant there.

Yes. By “versioning the website”, I did not mean “putting it into GitHub” (it already is on GitHub – the sources for the website are in the same repo as the spec itself). I mean “show all available versions of the spec on the website, instead of only the current development version”.

If you want an example of what I meant, you can have a look at the website for the “Next Generation File Format“ (NGFF – another spec I am involved with): https://ngff.openmicroscopy.org/specifications/index.html. The normative part of the NGFF website has all the versions of the spec so far, not just the latest one. That is what I’d like to have for SSSOM.