Preserve version picker function when the underlying filename changes

[dmuelle]

If we need to change a filename in the docs, the version selection for that topic is broken. This is not a high-priority issue, just opening to investigate possible solutions.

Eg- if we change development-mode.adoc to dev-mode.adoc, the URL changes
/docs/latest/development-mode.html ---> /docs/latest/dev-mode.html. We can set the following redirect in redirect.properties to cover most use cases: /docs/latest/development-mode.html=/docs/latest/dev-mode.html.

However, the version picker no longer works for the topic.

1. if you are on /docs/latest/dev-mode.html and select any previous version, you get a Document does not exist message.
2. if you are on any earlier version /docs/*/development-mode.html and switch to current version (or going fwd any version 23.0.0.7+), you get :

Document does not exist
The requested document does not exist in the 23.0.0.7 version of the documentation, but it is available in the following versions.
v23.0.0.7
v23.0.0.6
v23.0.0.5
....

which is interesting, but also contradictory. To recreate, see
Dev mode on the current draft site.

One solution might be to create individual redirects for each extant version, eg
/docs/23.0.0.4/dev-mode.html=/docs/23.0.0.4/development-mode.html

But those statements will become redundant with each release as older versions drop off and also will junk up redirects file over time if more file name changes are needed. However, at this point file name changes are relatively rare so that could be a stopgap solution if the alternatives are overly complex (or nonexistent).

This came up from a recent request to change a file name in the docs- OpenLiberty/docs#6726
As stated in that issue, to manually deliver a new file, new TOC entry, and redirects to all 26 versions where the file exists would be nontrivial, possibly requiring ~ 80 individual PRs. So changing the file name in all versions isn't a viable option.

[natalie-bernhard]

Hi David, is this filename change absolutely necessary? The way we know documents are the same across versions is by seeing that they have the same filename.

The UI is acting as expected for any undefined filename in a version. When the user switches from an older version to latest, it attempts to redirect the user to the file development-mode (retrieved from the previous URL), which is not found in the new version files, so the Document does not exist error occurs. When that error occurs, the logic checks if a link to the file in each version responds with a successful 200 code. However, since the redirect is there, the link exists and returns a 200 even though the file with that name doesn't exist for that version, which is why if you hover over the link matching the current version under Document does not exist, the link actually says development-mode.html, but the redirects handle the url once the link is clicked.

We could attempt to create a better way to check if the files exist, but this would not result in a successful linking between versions. This would require some source of external data, such as a JSON, to indicate aliases for files, which may be harder to maintain. I understand the motivation for wanting to change the filename, but from the perspective of handling the docs building and logic, the best thing would be to keep the filenames the same for now. If changing the filename is a necessity, let me know and I will look into further options. To be clear though, if we do go ahead with changing the filenames, a good portion of logic would need to be modified to handle it, and you likely would not be able to have differing filenames for at least a month, likely longer with the current resources available for the website.

We could exclude the current version of the docs when checking if the file exists in other versions, but this would then result in a blank Document does not exist error without alternate suggestions/links

[dmuelle]

Hi Natalie- thanks for this detailed explanation. As far as I know, this is not a crucial update. I think I can just close the doc issue, as the benefit of making the change is unlikely to justify the scope of work for the website team. If anyone from devex disagrees, we can revisit.

I'm not sure whether you want to keep this issue open and iceboxed but feel free to close it if not.

[natalie-bernhard]

Closing this issue for now as we have concluded that the benefits do not outweigh the cost at this time.