SLSA Tracks management strategy

[lehors]

Everybody seems to love debating versioning so here we go!

PR #1280 proposes to split the SLSA spec into several specifications:

1. The main SLSA spec
2. A separate spec for each track

The SLSA spec contains the general sections and only a highlight of what the different tracks provide with a pointer to each track for further details.

This setup has the advantage of allowing each track to be accessed, managed, and revised independently. However, this raises the question of how we want to orchestrate the release of the different tracks and the SLSA spec and manage the related versioning.

Option A - Publish and version the tracks independently from the SLSA spec

Every now and then, publish a new version of the SLSA spec pointing to different versions of the tracks.

• Pros: easiest to manage, provide the most flexibility
• Cons: creates two sets of version numbers, one for the SLSA spec, one for each track which can be quite confusing.

Option B - A variant of Option A in which we only use version numbers for the tracks and use dates for the SLSA spec.

In this scenario, SLSA 2025 could be made of, say, Build Track 1.1 and Source Track 1.0.

For what it’s worth, this is what is done for CSS for which “snapshots” are published every year or so, see: https://www.w3.org/TR/css-2023 and https://www.w3.org/TR/css-2023/#css-official

• Pros: reduces confusion to some degree
• Cons: the initially change from SLSA 1.0 to something like SLSA 2025 will be confusing in and of itself.

Option C - Keep the track versions in sync with the SLSA spec.

Every time we want to publish a new version of a track (or more) we publish a new version of the SLSA spec with all the tracks under the same version number (whatever it is according to our versioning scheme).

• Pros: simplifies the management of version numbers and limits confusion. Less of a departure from where we currently are.
• Cons: forces all tracks to be republished every time a track gets versioned, leading to multiple versions of a given track with no real changes. The what’s new section could make that clear though.

---

Note: This is a non-binding poll of a few options I thought about, feel free to propose other options!

[michaelwinser]

I think there's a lot of value in having SLSA's primary publishing vehicle be a single versioned spec. But I don't think that is incompatible with having versioned tracks. They are, for all intents and purposes, implementation details.

How this plays out with our current content solution is another question. I would rather not let the implementation details of our content generation drive the versioning experience for spec producers or consumers. Perhaps this is something we can revisit with some technical writing support.

Switching to a year-based versioning model for the SLSA spec will definitely put some pressure on to have a meaningful release each year. I don't think that's great but I'm not fundamentally opposed.

[arewm]

There are two primary challenges that I see with having versioning for SLSA and tracks.

1. If we version SLSA as something other than the tracks, what does the "parent" version actually include? Would its version need to be bumped if a track version is bumped? Is this effectively its own track with nothing but common definitions included?
2. When referring to levels, we already need to reference like SLSA v1.0 Build L4. If we version the tracks separately, how do we reference them? Would it be something like SLSA v1.1 Build v1.0 Level4? Or only have the versioning on the tracks with reference to the parent spec at a specific version like Build v1.2 references SLSA core v1.1 but BuildEnv v1.2 references SLSA core v1.2?

My understanding about part of the motivations behind SLSA v1.0 is simplifying it. If we are looking to simplify SLSA, we should have a single version for everything. We can still change this in the future if we get feedback that versions are changing too often or that we are not being clear.

Cons: forces all tracks to be republished every time a track gets versioned, leading to multiple versions of a given track with no real changes.

The tracks are not getting republished with every version in this model. The spec is getting updated with a new version. This can contain updates to some of the current tracks or it could contain new tracks. A change log/what's new is definitely a critical part of this model.

[klolive]

This is Kara, formerly @olivekl --- I contributed a lot to the early documentation and site. Weighing in from a tech writer point of view: I strongly support option C.

It looks like there's been an update to the site that muddied things a bit, but the idea at 1.0 launch was that everything under "Core Specification" would be versioned, and everything under "Understanding SLSA" would not be: see the breakdown here.

From a user-centric point of view, it makes the most sense to me to revert to that model, and keep all the tracks versioned together.

Option A and Option B make sense from the point of view of SLSA developers, but is there any benefit to the users? For them, I see only friction in having to keep track of more numbers and labels and to parse the difference between an overarching spec and versioned track.

The con listed for Option C ("Cons: forces all tracks to be republished every time a track gets versioned, leading to multiple versions of a given track with no real changes.") doesn't seem like a problem, really. There's an update, and some things stayed the same.

SLSA is complicated enough. I think separate versioning would make it even harder for users.

[lehors]

Thanks @klolive for chiming in.

The "Understanding SLSA" sections have been versioned along with "Core Specification" since before the publication of SLSA 1.0. For that matter, the Attestation formats section was also folded into the same versioned package. As far as I can remember the rationale was that there were some dependencies between those different pieces and the only way to keep things consistent was to package them all up together.
This being said I also feel this may have gone too far and I have wondered whether we should split these back but the point that some references might break when moving from one version to another is real. For instance, in 1.1 we have changed the threats model see threats 1.0 vs threats 1.1 and any text in the spec that refers to it would become invalid.

As for the different options here I tend to agree that we should prioritize ease of use over ease of maintenance and even if it makes things a bit more cumbersome for us to keep all the pieces in sync option C would definitely make it easier for people to consume.

[arewm]

As for the different options here I tend to agree that we should prioritize ease of use over ease of maintenance and even if it makes things a bit more cumbersome for us to keep all the pieces in sync option C would definitely make it easier for people to consume.

I agree with this statement. 😄

[michaelwinser]

Having read the above discussion, I'm in favour of Option C.