More nuanced version support: Visually differentiate latest from supported from deprecated about documentation-builder

[nottrobin]

Would it solve this problem to update the versions file to be more explicit:

primary_version: 2.2
supported_versions:
  - 2.1
  - 1.7
deprecated_versions:
  - 2.0
  - 1.6

And then just add a small conditional to the template to display a banner to explain which type of version you're on?

[pmatulis]

I think more like this:

stable_version: 2.2
supported_versions:
  - 2.2
  - 2.1
  - 1.7
deprecated_versions:
  - 2.0
  - 1.6

Do we need that exact spacing (2 spaces, dash, space)? I'd rather avoid it, to minimize typos.

And then just add a small conditional to the template to display a banner to explain which type of version you're on?

I'm unsure what template you're referring to and what the banner would look like. Is a watermark out of the question? Users can land on anchored links or may simply not notice a banner.

[nottrobin]

@pmatulis if we're going for this sort of more complex data I want to use a standard format, and YAML is the most common standard. So any valid YAML will work. supported_versions: ["2.2", "2.3"] would also work. I think I'd rename the file to version-branches.yaml or something to make the format clear.

Could that first key be latest_version or latest_stable_version if you'd rather? Surely more than just the one version will be "stable". I'm fine with having overlap with the supported_versions if you like.

[pmatulis]

Sigh, YAML. I have found it is often a source of whitespace-rage and this file's format should be dead-simple in order to minimize errors that will manifest down the pipe (publication process).

I chose "stable" carefully. There is only one stable set of docs at any one time. This intersects with the request for a way to link to stable doc pages.

@evilnick ?

[evilnick]

We already have a no-format solution for that. We have "versions"(=list of current docs) and "archives"(=published but hidden). See Juju docs

[nottrobin]

To me, "stable" means basically "supported, not beta". As in "this shouldn't have serious bugs".

I am open to suggestions for a better standardised format that allows us to specify lists of branch names. But YAML is used for this sort of file throughout our projects, so many people in the company are familiar with it (perhaps because Mark likes it).

[evilnick]

If it is deemed necessary to roll it all into YAYAML file, I suggest it just gets rolled into the metadata.yaml

[evilnick]

P.s. I think a banner is fine

• an informational one suggesting you are not on the current version for old-but-supported
• an angry looking one when you are on the archives

both should link to current stable

Also, I am happy with 'default_version', which has no extra connotations

[nottrobin]

@evilnick I'm happy to follow the juju docs format of having 2 separate files if you like - presumably we can infer that the top row of versions is the main version (as I think we discussed before)?

We still have the question of whether "stable" is the right word, because we'll use this wording in the banner to link to the top version on older version pages.

These versions presumably don't refer to the documentation versions, they refer to the software versions. I don't like calling the top version "stable" because it implies that the other "supported" versions aren't "stable" - in that they're buggy. I'd rather call it "the latest version", but I'm fine with calling it "the latest stable version" if that would help you.

[pmatulis]

But we already use the term 'stable' on the version selector on https://jujucharms.com/docs to mean the latest stable version. When you click on the above link you end up on https://jujucharms.com/docs/stable/getting-started.

@evilnick Here is the issue. :)