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?

[zacdezgeo]

@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.

[wildintellect]

@rtapella we briefly had a discussion on the Data Team side today, and thought of a way to make this clearer.

Proposal

• Stable -> Master (this is released docs for existing features) and should be the Rtd default
• Latest -> Develop (this is docs in the works), maybe should only be for existing features
• ? -> (staging)? for features that might not be available to users yet, developers only, this let's us work on describing new features not released yet without blocking general doc updates.
• Tagged versions, since we push to Master whenever we have more docs ready not only at releases this is a challenge to version. We don't want people going to 4.1.1 docs which may be missing things since we've pushed more docs after the release.

Staging and Develop names could be swapped if that makes more sense to people.

cc: @zacdezgeo @smk0033

[rtapella]

Thanks @wildintellect ... for the tagged versions, I think it might be okay to use the semantic versions when they sync up with a platform release. Typically for a new platform release we add release notes plus any platform docs (system ref. guide and/or platform tutorials) to the versioned release.

If we release to the master-branch in-between versions that's okay (?), it just won't get a particular semantic version. I think the way to not miss things is to use the default/Stable.

I am not really clear on when someone would use the "rewind" versions... e.g. when/why would I look at the version 2 docs at this point? Is it important that i don't miss version 2 +extras? (docs published between v2 and v3)

[zacdezgeo]

@rtapella; we talked about your last question:

I am not really clear on when someone would use the "rewind" versions... e.g. when/why would I look at the version 2 docs at this point? Is it important that i don't miss version 2 +extras? (docs published between v2 and v3)

It's unlikely right now but if someone is running an outdated version of MAAP and the docs refer to features they don't have available they may want to compare previous docs versions. They can always refer to a specific commit or branch on github, it's just harder to navigate.

[rtapella]

A ReadTheDocs maintainer could set up a separate branch to manage that situation, and publish that. Considering the rarity of the situation maybe that's okay for now? If so... we could ignore the in-between release+extras as an automatically handled case. Latest or Master will be available for the current in-between-release docs.

Separately:
I think we can handle develop as "released features only" and only do a x.x.x-feature-branch merge when we're doing a platform update, including new features. (docs: x.x.x -> develop -> master when the platform-code update x.x.x is released)