Deprecated extension documentation link is broken

[jpeach]

The deprecation warning emitted when a deprecated feature is used contains a documentation link that is 404.

[2020-05-06 00:14:08.017][1][warning][misc] [bazel-out/k8-opt/bin/source/extensions/common/_virtual_includes/utility_lib/extensions/common/utility.h:65] Using deprecated extension name 'envoy.grpc_web' for 'envoy.filters.http.grpc_web'. This name will be removed from Envoy soon. Please see https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated for details.

The link https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated returns 404

$ curl -L -v https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated
*   Trying 157.230.37.202:443...
* Connected to www.envoyproxy.io (157.230.37.202) port 443 (#0)
* ALPN, offering http/1.1
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate: envoyproxy.io
* Server certificate: Let's Encrypt Authority X3
* Server certificate: DST Root CA X3
> GET /docs/envoy/latest/intro/deprecated HTTP/1.1
> Host: www.envoyproxy.io
> User-Agent: curl/7.70.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 404 Not Found
...

[alyssawilk]

Whoops, I think that's due to the generally awesome docs refactor in #10730

We could point folks to https://www.envoyproxy.io/docs/envoy/latest/version_history/version_history instead, but making them wander through pages doesn't seem as useful. Per Matt's point over in #11058 I wonder if we can leverage the annotations to print out something field-specific and useful, or just point them at API docs which will be specific and useful?

@ggreenway @mattklein123 @htuch

[htuch]

In this specific case, this is just the new vs. old names for extensions, so we can provide a fixed anchor.

It should be fairly easy to autogenerate a link back to the field specific docs in general though, from browser copy+paste, this is what the href looks like: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-field-config-core-v3-healthcheck-transport-socket-match-criteria

[ggreenway]

Ideally, we'd have a released version not point at latest, but at it's version of the docs, so any future movement of pages won't invalidate those links.

Field-specific doc-links would be great, but I don't know if it's worth the effort or not.

[mattklein123]

Ideally, we'd have a released version not point at latest, but at it's version of the docs, so any future movement of pages won't invalidate those links.

Yeah this would probably be the "simplest." I wonder if it could be done with a short generated header/cc file that is based on the VERSION file?

[htuch]

We already have this constant that we use for the build version string.

[jpeach]

Independently of how this link will be managed in the future, shipping envoy versions are emitting this message today. Is it possible to add a redirect to support people who are currently seeing this message?

[jpeach]

xref #8465

[mattklein123]

Is it possible to add a redirect to support people who are currently seeing this message?

Doc PRs appreciated.

[ggreenway]

I'll fix this soon. My mess, mine to cleanup :)