Edit button doesn't work for versions based on tags

[medubelko]

Background

We changed the edit button to point to the editable links in GitHub. It used to be:

https://github.com/canonical/snapcraft/blob/8.11.1/docs/index.rst

For projects where versions were based on tags, the user could see the state of the repo at that tag. While it wasn't ideal, because there was no editable interface, at least the user could see the code.

It's since become:

https://github.com/canonical/snapcraft/edit/8.11.1/docs/index.rst

Now the button fails critically because the link is a 404.

Request

Tag-based versions are the most common case for semantically-versioned projects, so we must support them.

1. Make the edit button detect the project's tags.
2. When the project has tags, point to a branch (usually hotfix-semver) where the editing interface is available.

This will likely require some manual configuration where the project maps hotfix branch semantics to tags, because there's no way to guarantee that a tag has an available branch associated with it.

[SecondSkoll]

Would it be better to check the build environment and conditionally disable that button?

We don't have a generic pathway for revising existing versioned docs. Projects won't normally have a branch for each published tag to be able to provide a place for fixes - and the creation of hotfix branches should probably be manual (we have some cases of people just hitting buttons and submitting empty issues).

If an issue is identified with a pinned version they can still use the "Give feedback" button to raise an issue for it to be fixed.

I suppose the main problem is that if set up in the way I describe, the docs will default to a stable branch which also represented a pinned version. Is this a human problem where we should have a stable-docs branch?

[medubelko]

I'm not suggesting this become the default way of looking at versions, just that the system becomes robust enough to handle the case of tags, since tags are one of two principal ways of creating versions in RTD. I would hope this would scale to any project that uses semver.

Would it be better to check the build environment and conditionally disable that button?

Craft products, and I think all docs, need the button. Crafts probably need the button more, since finding exactly where on GitHub version x.x.x of the text lives is a pain. This is what Snapcraft users face:

We support craft apps for five years, so I don't think limiting edit functionality to stable is a good experience. If a user wants to fix the docs for the core22 version of the app, they'll be frustrated if all they can easily find on GitHub is the core26 docs on main.

the creation of hotfix branches should probably be manual

Where the tag comes from is irrelevant in this mode. The tag is detected in the repo, so a version is created.

Is this a human problem where we should have a stable-docs branch?

It's a human problem, but in the semver/GitFlow world, evergreen isn't really a thing, unfortunately. Stable is the latest tagged version, not main. We either have to decouple the docs from the product, or deal with its versions in one way or another. The goal of this issue is to handle as much of this tangle as possible through code.

I've raised the complexity of versioned docs in thinly-sliced products elsewhere. It's difficult to marry internet concepts (docs-as-website) with long-lived, standalone, atomic software releases. Happy to chat about it directly.

[SecondSkoll]

I might not have been clear enough. I'll run through my thinking - just for anyone else looking at this:

Context and thought process

Make the edit button detect the project's tags.

While we can check the version type (branch or tag), most projects are using tags (and the ones using branches have issues with getting stable to work). To detect the actual tag in use, os.environ["READTHEDOCS_VERSION"] renders to <tag-version> / latest / stable with stable builds actually being a different build to just the latest tagged version (stable vs specific tag). Your stable docs only know their version from the set release in the config - which does in your case, but may not for others, map to the tag in use.

So mapping docs to specific tags is only possible for the versioned ones, or a project like snapcraft with good automated and manual processes.

Anyway, yes, we can identify when we're on a tag based version - and we can mostly know what the source tag is.

When the project has tags, point to a branch (usually hotfix-semver) where the editing interface is available.

From what you're suggesting you want to see someone hit the edit button and automatically find themselves in a hotfix branch of that version to be able to make revisions. However, a branch of the content from a pinned docs version isn't going to be available unless the project is specifically set up that way. You don't have 33 hotfix branches set up for changes to those versions. To make a change, you need to branch from a specific tag/commit, make revisions, and retag the branch. I don't believe we should do the first part of that with a single push of the edit button (find tag - branch - present page to edit).

...

Hmm. I suppose I was slightly off base. From looking at how we've set things up - we don't provide a feature to overwrite html_context["build_branch"] in the build environment. Is that all we want in this case? I just don't think it solves the overall problem identified here.

When the project has tags, point to a branch (usually hotfix-semver) where the editing interface is available.

We can provide functionality to point to a specific branch, but which branch essentially needs to be manually configured - and it will be complex to have these branches reflect the state of the existing tags.

I just don't see a strong argument for this when configuring this appropriately just ends up with having a 1:1 mapping of branches to available doc versions - and in that case why not just have branch based versioning?

If we do implement this, and I think it's a good idea to do in some way, I think that there should be a default - and the default should be disabling the edit button on tag based versions - it's better than providing a broken link or a link to a a branch that does not reflect the current status.

I propose:

Allowing configuration of html_context["build_branch"] even in an RTD environment - which you could conditionally implement in a project by detecting information in RTD's build environment. You would need to set up branches and configure them, and specifically point to them using this config. If you don't have it html_context["build_branch"] set, and the environment detects a tag based version, it would disable the button so we don't provide a broken edit function.

[medubelko]

I think we're quiet largely in agreement, but I probably emphasised the less-important bits. :)

I could implement a solution in the Starcraft tooling, but I'd really like if everything we do is available for all projects. Juju, for example, has a similar need.

You would need to set up branches and configure them, and specifically point to them using this config.

Agreed! I wanted to be lightweight with the logic and user config:

1. Fetch all the repo tags and branches. Doing this by default might be too expensive, but let's table that for now.
2. If READTHEDOCS_VERSION_TYPE == "tag", check if the tag matches any branch names. This covers the case where the branch and tag names are the same.
3. If no matches found, check for a special config setting, which defines a tag naming pattern and a branch naming pattern. For Starcraft the intent would be to fuzzy-match tags 8.10.x to branch hotfix-8.10. For Juju, it would be to match tags v3.6.x to branch 3.6.
4. If that setting exists, use it to check for a hit. If result, use that branch name in the edit button link.

I just don't see a strong argument for this when configuring this appropriately just ends up with having a 1:1 mapping of branches to available doc versions - and in that case why not just have branch based versioning?

Agreed, that wouldn't make users' lives easier.

If you don't have it html_context["build_branch"] set, and the environment detects a tag based version, it would disable the button so we don't provide a broken edit function.

I think you're right, it's probably best to avoid checking tags if the RTD config and repo don't match our ideal setup. But I think defaulting to main is better than nothing at all. I personally think the user should have to opt out of the edit button.

[jahn-junior]

In recent discussions surrounding this button, a few team members mentioned that it may be better to direct users to the page source rather than directly to the GH web editor. If we send users straight to the web editor, first-time contributors are prompted to create a fork before they're even shown the source, which may not be the ideal journey.

This is somewhat tangential to the issue of tag-based versioning, but it's something to consider while this feature is under the knife.

[rkratky]

If no matches found, check for a special config setting, which defines a tag naming pattern and a branch naming pattern. For Starcraft the intent would be to fuzzy-match tags 8.10.x to branch hotfix-8.10. For Juju, it would be to match tags v3.6.x to branch 3.6.

I'm afraid this would prove rather brittle IRL because projects use all kinds of naming/versioning patterns. Also, some projects where docs live alongside the code tag version releases without branching for the released versions. When a bug is found in the SW, they tag a new version and re-release. Depending on the project's governance, they might or might not want to do the same when it's ("only") a docs bug. So, branching off a tag for a docs fix might not be their desired/expected behavior.

IOW, I believe we should make this (disabling the button when a tag-based release is detected, or doing $something else) configurable.

I think you're right, it's probably best to avoid checking tags if the RTD config and repo don't match our ideal setup. But I think defaulting to main is better than nothing at all. I personally think the user should have to opt out of the edit button.

Defaulting to main could be confusing for users because they might assume they're fixing the docs from which they clicked the edit button, but instead they'd be submitting a fix against main (which would not have any affect on the tagged release).

Also, the content in main may differ from whatever is in the tagged docs release, so the user could be brought to a doc that is not the same as the one they wanted to fix.

[medubelko]

Also, some projects where docs live alongside the code tag version releases without branching for the released versions. When a bug is found in the SW, they tag a new version and re-release. Depending on the project's governance, they might or might not want to do the same when it's ("only") a docs bug. So, branching off a tag for a docs fix might not be their desired/expected behavior.

Thanks for the data! I'd like to begin collecting all the cases this would need to work for.

Could you link the different repos that have different release patterns you're mentioning?

[rkratky]

Could you link the different repos that have different release patterns you're mentioning?

@edibotopic?

[edibotopic]

For Ubuntu on WSL we have a latest docs version associated with the main branch, and a stable docs version associated with the last tagged version. If we urgently need to fix something docs-related on latest then we create a new tag. In reality, the latter case has typically been reserved for exceptional circumstance, such as recently when we were applying fixes during a launch.

As another example, for authd, we have a stable-docs version associated with its own branch, in addition to the usual edge-docs (latest) associated with main.

For WSL, we cannot currently use the edit button, as it works on latest but not on stable. In the case of authd, we can use the edit button as there are branches associated with each version

Defaulting to main could be confusing for users because they might assume they're fixing the docs from which they clicked the edit button, but instead they'd be submitting a fix against main (which would not have any affect on the tagged release).

Based on my experience, with the particular docs sets that I am responsible for, this wouldn't be a problem. That's because if we spot an issue in stable then we would make the fix in latest and wait for that fix to be applied in the next tagged release --- the contributor would simply be following that approach, although perhaps it could be signaled to them in some way ("Thanks for your contribution. It will apply to the latest version of the docs for now and the stable version in our next release"). For us as maintainers, something usually has to be show-stopping for us to urgently need to update stable.

Importantly, that solution ("edit defaults to main") is still better than the current implementation for me, which I simply cannot use in docs with tags. I would rather a user be directed to main than a 404. One option would be to allow enabling the edit button in the latest/main version only, which would mean both that people are afforded the opportunity to edit the latest in-development version while not being subject to indirection when they edit a non-latest version and are then forced to edit main. I think it's not unreasonable that the latest/dev version of the docs would be open to hotfixes but not others, but it could be left for maintainers to decide.

[edibotopic]

Separately, but related, if a maintainer wants to disable the edit functionality but still allow a user to read the source, is it possible to enable a "show source" option that displays the source of a page in plaintext?

I couldn't figure out how to do that when I was removing the edit functionality. While the implementation of the edit feature is being developed, it would be useful to have "show source" clearly documented as an alternative, if it is still available.