Puzzled about version numbers and documentation

[gpdf]

I'm trying to figure out a few things about ASDF and its version numbering.

I just spotted the announcement of a "1.1.0" release of this repo: https://github.com/asdf-format/asdf-standard/releases/tag/1.1.0

The release announcement's contents mention

The in progress ASDF Standard is v1.6.0

The stable ASDF Standard is v1.5.0

which is a little puzzling when compared to the history of tags on the GitHub repo.

The CHANGES file going back to its beginning has always mentioned the same two version numbers for the standard. My guess at what this means is that any given snapshot of the repo actually contains both the 1.5.0 "stable" standard text and the evolving "1.6.0" text. But I've gone looking for this, concretely, and can't find it, at least not very easily.

Naively I would have expected something like a "1.5.0" release/tag on the main branch and something like an rc-1.6.0 branch, perhaps with a succession of pre-release 1.6.0-beta1 sorts of tags.

There's additional puzzlement on the doc-build side. The repo points to http://asdf-standard.readthedocs.io/ as its documentation site, but that site produces a 404 error. Doing a Web search turned up an http://asdf.readthedocs.io/ site, but that is for the library.

Doing some guessing of URLs turned up https://asdf-standard.readthedocs.io/en/latest/index.html and https://readthedocs.org/projects/asdf-standard/versions/

The latter page seems to list a mix of the GitHub versions 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.1.0, and the "nominal" versions 1.5.0 and 1.6.0.

Can you clarify this, and fix the top-level doc link URL http://asdf-standard.readthedocs.io/ to work?

Many thanks, Gregory

[braingram]

Thanks for opening an issue. I'm going to pin it as it mentions that the docs are broken. They most certainly are due to RTD failing to build the latex version: https://readthedocs.org/projects/asdf-standard/builds/23658134/ That will hopefully be addressed soon and unfortunately was not caught by any of the CI.

As far as versioning it is certainly confusing and we are considering a fix (more on that below).

This repo contains 2 versioned things:

• the ASDF standard which is language independent and currently has it's stable version of 1.5.0
• the asdf-standard python package (which provides the ASDF standard schemas to the python ecosystem) which just released 1.1.0

The 2 versions are as you noted confusing and we're considering tying the 2 together (so making a new release of asdf-standard that will jump forward to 1.6.0 when ASDF-standard 1.6.0 is released. However there are additional considerations as the asdf-standard packages provides a bit more than just the schemas (such as the DirectoryResourceMapping) and linking the ASDF standard version to the asdf-standard python version would mean that a version bump for that package would also bump the ASDF standard version (which is harder to version as each new version requires at least one new file).

I hope this clears things up and please let me know if there is something that you think could be done to help clear this up.

[braingram]

I'm unpinning this as 1.1.1 was released which fixed the docs: https://asdf-standard.readthedocs.io/en/1.1.1/ doesn't 404 and https://asdf-standard.readthedocs.io redirects to above.

[gpdf]

Thanks for getting the doc-deploy fixed.

I understand the bind you are in, but I'm glad to hear you are considering a revision; I think the current situation would be permanently confusing.

Here's the presentation on the docs site now -- there's not a mention of 1.5.0 or 1.6.0, so it just looks outdated to anyone who has heard of 1.5.0 or 1.6.0 but who isn't aware of the nuances:

I don't want to pursue this further personally -- you've explained the situation promptly and clearly (thank you!) and I can find the documentation we need (and pass these tips on to others in my team) -- but I do hope you can find some alternative solution.

Perhaps your explanation above could be added to https://asdf-standard.readthedocs.io/en/1.1.1/versioning.html in the mean time?

[braingram]

Adding a description of the package version to the link you shared sounds like a great idea! I'll leave this issue open to track that change.

I hid the 1.5.0 and 1.6.0 docs as they are very out-of-date.

[acovaci]

@braingram the 1.6.0 is still very much indexable/accessible via search, and at least on my end, it supersedes 1.1.1 in search results: https://asdf-standard.readthedocs.io/en/1.0.1/schemas/yaml_schema.html

I'm not sure if there's any way to make a "rewriting history" kind of change, but this highly confused me and might need changing. At the very least, maybe adding a notice on the current docs, specifying that we are indeed browsing the correct version, and linking to a short explanation?

EDIT: Although, with ASDF Schema 2.0.0, this would be significantly less impactful.

EDIT 2.0: Now, after reading the entire conversation in detail, I understand why this is the case (decoupling between the standard and the documentation). I would even suggest moving the standard to a different platform, such as GitHub pages, similar to the Rust Book, for example: https://doc.rust-lang.org/book/ The reason for this is (at least in my brain), a web page would supersede a docs page in terms of importance when first coming across a new tool/standard/etc.