Link to the "latest" version of documentation for particular pages

[szpak]

Is your feature request related to a problem?

People willing to link to the latest version of the release notes have to link to the .adoc file in Git instead of https://spockframework.org/ - e.g. here

Describe the solution you'd like

https://spockframework.org/spock/docs/latest/release_notes.html (or "current" instead of "latest") should redirect to the latest (stable?) version for every subpage.

Currently one can use https://spockframework.org/ or https://spockframework.org/spock/docs/ , but it doesn't work for linking to the particular subpages.

Describe alternatives you've considered

No response

Additional context

No response

[leonard84]

Do you have a good suggestions how to achieve that? Currently, it is a manual process, see https://github.com/spockframework/spock/commit/874075117e0c947e9c3b03b3d2f5249e070ce139 relying on <meta HTTP-EQUIV="REFRESH"...>

[szpak]

Do you have a good suggestions how to achieve that? Currently, it is a manual process, see 8740751 relying on <meta HTTP-EQUIV="REFRESH"...>

Here you checked if a symlink at the directory level coudn't be used with GH pages?

docs/current -> docs/2.3 (updated from the CI server)

[leonard84]

🤔 this could work, the "downside" is that https://docs.spockframework.org/ wouldn't redirect to a stable link anymore, but to one that will change when updated. This could leave links with broken anchors if the sections were removed/renamed.

[szpak]

Good point with more problematic sharing links to the exact version :-/.

Maybe we could have "current" with the current (no pun intended) behavior (used for people visiting https://docs.spockframework.org/) and (for example) "latest" with the symlinks (for the special use cases, such as aforementioned)? The difference could be mentioned somewhere in the documentation.

I know that "latest" is currently used for really latest SNAPSHOT version, but for people willing to reach that version (to test if changes in master with documentation work fine?) could use the exact link instead. Or we could make up some new word :-).

[szpak]

I gave it a try in a separate repo and it works as predicted.

https://szpak-forks.github.io/pages-refresh-current/docs/2.3/ - stable 2.3 https://szpak-forks.github.io/pages-refresh-current/docs/2.3/page1.html

https://szpak-forks.github.io/pages-refresh-current/docs/current/ - redirects to docs/2.3/ https://szpak-forks.github.io/pages-refresh-current/docs/current/page1.html - broken (as currently)

https://szpak-forks.github.io/pages-refresh-current/docs/always-current/ - always current https://szpak-forks.github.io/pages-refresh-current/docs/always-current/page1.html - always current, works also for particular pages

So, I would keep "current" and "latest" as is (with redirect) and "???" (always-current?) as an "always current link to the (latest) current stable version". The question is: how to name it?

current-stable (with "stable" as in a "stable link" to something) could be misleading (due to a stable version). current-latest - the same situation. perma-current - "perma link" suggests rather a link that will always refer to the same. I don't have a good idea :-/.

[szpak]

@leonard84 WDYT about the last proposal?

[leonard84]

Sounds OK, ideally this would be automated during publishing. Would you like to give it a try? The best place would be a small plugin in build-logic.

[leonard84]

Alternatively, we could add a task that goes through the published docs and adds a header with the different versions and displays a warning, when it isn't the latest one. Similar to what Postgres is doing.