Inbound links to specific git version docs broken, should at least redirect to the closest version

[vassudanagunta]

URL for broken page

https://git-scm.com/docs/diff-options/2.15.0

Problem

This page was linked to by a StackOverflow answer and recently reported dead.

I can see why git-scm.com/docs would not want to have every patch release in the dropdown on that page, but dead links are bad for the internet, and should be avoided when possible, at the very least by a reasonable redirect.

Alternatives:

1. keep the pages for every patch release, but simply only keep the latest patch versions in the drop down as you have today.
2. redirect URLs to the removed patch versions to the more recent version that replaces it in the historical docs. In the above case, docs/diff-options/2.15.0 would redirect to docs/diff-options/2.15.4
3. A better 404 page, e.g. that suggests a link to most relevant alternate page.

[dscho]

2. redirect URLs to the removed dot versions to the more recent version that replaces it in the historical docs. In the above case, docs/diff-options/2.15.0 would redirect to docs/diff-options/2.15.4

That should be the most feasible, even if it will blow up the number of generated files. The necessary change would need to be made here

3. A better 404 page, e.g. that suggests a link to most relevant alternate page.

This is an interesting idea; It would seem that Javascript could be used (window.location.pathname seems to contain the string "/docs/diff-options/2.15.0" in the indicated example). Something like this should do the job:

const match = window.location.pathname.match(/^(.*\/docs\/[^/]*)\/[0-9.]*$/)
if (match) window.location.replace(match[1] + window.location.search + window.location.hash)

If you want something more sophisticated than to redirect to the newest version, you could play games with AJAX HEAD requests that try a couple of increasing patch-level versions until it finds a matching version (falling back to the newest version, as outlined above).

[EDIT]: That Javascript code would need to be added to this file: https://github.com/git/git-scm.com/blob/gh-pages/content/404.html

[vassudanagunta]

Another option:

4. Going forward exclude the patch version from the URL, e.g. docs/diff-options/2.15. Configure the webserver to autoredirect all URLs with a patch version to the corresponding minor version URL.

[dscho]

Configure the webserver

Please notice that git-scm.com is hosted on GitHub Pages.

[vassudanagunta]

Understood. Then I assume your implementation for option 2 would generate an HTML page for each redirecting URL with a <meta http-equiv="refresh" ...> element? That approach has the advantage of giving the reader a chance to see a message about redirect specifics, e.g. like this demo GitHub Page.

If you want something more sophisticated than to redirect to the newest version, you could play games with AJAX HEAD requests that try a couple of increasing patch-level versions until it finds a matching version (falling back to the newest version, as outlined above).

Couldn't the <meta http-equiv="refresh" ...> effectively do this statically, i.e. point to the latest patch for that version rather than the latest overall version?

[dscho]

I assume your implementation for option 2 would generate an HTML page for each redirecting URL with a <meta http-equiv="refresh" ...> element?

Yep, and that's a problem. It's already a lot of files.

That approach has the advantage of giving the reader a chance to see a message about redirect specifics

No, it would be an automatic redirect too fast for the reader to have a chance to read it.

If you want something more sophisticated than to redirect to the newest version, you could play games with AJAX HEAD requests that try a couple of increasing patch-level versions until it finds a matching version (falling back to the newest version, as outlined above).

Couldn't the <meta http-equiv="refresh" ...> effectively do this statically, i.e. point to the latest patch for that version rather than the latest overall version?

Not unless you want to balloon the number of .html files by a factor larger than 10x.

[dscho]

@vassudanagunta have a look at #1928. You can see the effect e.g. at https://dscho.github.io/git-scm.com/docs/diff-options/2.15.0.

[vassudanagunta]

First, I think the more helpful 404 in #1928 is great! 🎉 I'm not pressing you to do more! :)

That said,

Yep, and that's a problem. It's already a lot of files.

Maybe that's not really a big deal? I don't know, just wondering.

No, it would be an automatic redirect too fast for the reader to have a chance to read it.

<meta http-equiv="refresh" ...> supports a delay, like the demo link I gave above.

I wonder, what if you added JS logic to the new 404 to autoredirect to the page it suggests, after a delay of 10 secs? Something to consider after what you just coded sits a while.

It's too bad you can't get analytics for GitHub Pages, to see how often this happens, without adding third party tracking.

Should I close this now or wait for #1928 to be deployed?

[dscho]

First, I think the more helpful 404 in #1928 is great! 🎉

Thanks.

I'm not pressing you to do more! :)

Well, you could always start working on this yourself. That's kind of what I have expected already.

That said,

Yep, and that's a problem. It's already a lot of files.

Maybe that's not really a big deal? I don't know, just wondering.

Have a look at the deploy times. Maybe, hopefully, that will make you rethink that statement.

No, it would be an automatic redirect too fast for the reader to have a chance to read it.

<meta http-equiv="refresh" ...> supports a delay, like the demo link I gave above.

The entire proposal is based on the idea to let JavaScript do the redirection. JavaScript cannot use that http-equiv construct.

I wonder, what if you added JS logic to the new 404 to autoredirect to the page it suggests, after a delay of 10 secs? Something to consider after what you just coded sits a while.

Here is something else to consider while the code sits for a while: How about actually getting active and not let other people do all the coding? Just an idea. (The idea behind open source.)

It's too bad you can't get analytics for GitHub Pages, to see how often this happens, without adding third party tracking.

It is really too bad. However, I fail to see how that would benefit us in this particular scenario.

Should I close this now or wait for #1928 to be deployed?

It is already set to autoclose when the PR is merged. No need to do that manually.

[vassudanagunta]

Here is something else to consider while the code sits for a while: How about actually getting active and not let other people do all the coding? Just an idea. (The idea behind open source.)

You made some assumptions there.

I quit my corporate job 11 years ago and write (prose) and do software dev that i will release as open source, and do volunteer work. All my work now is toward social good. I live on less than 15k a year. I used to make 6 figures. :)

[dscho]

Here is something else to consider while the code sits for a while: How about actually getting active and not let other people do all the coding? Just an idea. (The idea behind open source.)

You made some assumptions there.

I did really not assume anything here. Instead, I observed that you had not written even a single line of code, but instead suggested changes that could not work which would be obvious to anybody who had looked at the code.