Tags out of date

[wildintellect]

We have not kept up with Tagging the docs when doing major merges to Develop

Each time we merge to Develop we're supposed to tag the current version so that it can be found in the history, and navigated to on ReadTheDocs. The current Develop should probably be tagged 4.1.0?

Additionally a new feature on ReadTheDocs might confuse users. 'Latest Version Notification' https://about.readthedocs.com/blog/2024/04/enable-beta-addons/ shows a popup when you go to latest (which is the Develop branch). However for us this is actually the most up to date documentation, there are no not yet implemented features in the docs.

@rtapella we might need to rethink the naming strategy of the branches and the configuration on the ReadTheDocs to make sure people are going to the best version of the docs and knowing it matches what they are using.

[wildintellect]

@zacharyDez maybe you have some thoughts on how to straighten out our tags, and reconfigure RTD to not be confusing?

[zacharyDez]

@wildintellect on the latest version notification, I did some research. I found this discussion on addons. It seems there isn't a clear option for disabling addons at the time. We can change the configuration used for themes, but that does not give us access to disable the warning. The simplest apporoach seems to be setting the display value to none on the .rtd-version-warning class: _static/custom.css

[...]
.rtd-version-warning {
  display: none;
}

[rtapella]

When we update the docs for a release, we do make a documentation release as well (https://github.com/MAAP-Project/maap-documentation/releases). As a result, there is a tag in the potential list of docs for each release (we are not showing them though).

Potentially we should tag some additional merges to develop.

Latest for us is actually the master branch:

[rtapella]

(when we do a release, we merge develop -> master, cut a release (giving it a tag and version), and "latest" has the latest release of documentation)

[rtapella]

Maybe latest should be develop, and stable should be master?

[rtapella]

And actually I am not sure if "latest" just happens to be master at the moment b/c that was the most recently updated.

[wildintellect]

@rtapella the reason "latest" is master is because it's a released version - also we specified this in the RTD settings. "Develop" was envisioned to potentially contain docs about features that users can't use yet.

I agree that it's a mess and confusing, hence the ticket. As per the tagging, current tag == "latest" so no reason to show, but anything older than that should get enabled for historical reasons, or hidden because it's no longer valid.

[rtapella]

Just making some notes here Current situation:

RtD / defaults to RtD latest GH master -> RtD latest branch or tag with name following semantic versioning -> RtD stable GH develop -> RtD develop any arbitrary GH branch or tag -> name of branch or tag (must be manually activated in RtD)

When a new release is made:

• feature branch merged to develop
• develop merged to master
• release created with new semantic version
• that becomes "latest" (bc it's in master) and "stable" (bc of semantic version)

In-between releases:

• feature branch merged to develop
• either a scientist uses develop RtD or the develop Git branch is pushed to Git master and it becomes the latest RtD

[rtapella]

So question:

• do we want to also have tags on GH develop builds, so that they will build in RtD "stable"?
• if the current process is followed, does it work out okay? We do have semantic version tags for each "platform" release version, which (because it's in master) goes to latest and to stable
• if we want to official update the docs off-cycle with the platform (workspaces), it's possible by merging develop into master, which will then be RtD latest (but not stable, because it does not have a release/tag version)
• do we want to also show some recent releases, or older releases of the docs? RtD versions already exist for those but are not shown

[rtapella]

Typically "latest" is what someone will want. "Stable" will usually be the same as "latest".

If someone needs to look at in-development docs, then develop is available, or we can manually show a feature-branch.