docs: Fix broken link to 7.16 docs

[bmorelli25]

The docs PR to upgrade to 7.16 (elastic/docs#2299) is failing due to a broken link in the apm-agent-nodejs repo. This link exists in master, 3.x, and 2.x:

14:29:51 INFO:build_docs:Bad cross-document links:
14:29:51 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/apm/agent/nodejs/2.x/log-correlation.html contains broken links to:
14:29:51 INFO:build_docs:   - en/apm/guide/7.16/observability-integrations.html#_ingest_your_logs_into_elasticsearch
14:29:51 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/apm/agent/nodejs/3.x/log-correlation.html contains broken links to:
14:29:51 INFO:build_docs:   - en/apm/guide/7.16/observability-integrations.html#_ingest_your_logs_into_elasticsearch
14:29:51 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/apm/agent/nodejs/current/log-correlation.html contains broken links to:
14:29:51 INFO:build_docs:   - en/apm/guide/7.16/observability-integrations.html#_ingest_your_logs_into_elasticsearch
14:29:51 INFO:build_docs:  /tmp/docsbuild/target_repo/html/en/apm/agent/nodejs/master/log-correlation.html contains broken links to:
14:29:51 INFO:build_docs:   - en/apm/guide/7.16/observability-integrations.html#_ingest_your_logs_into_elasticsearch

This PR adds an asciidoctor ifeval that changes the documentation link based on the{branch} attribute specified in this file. After the 7.16 release, this ifeval can be removed as only the {apm-overview-ref-v}/log-correlation.html#_ingest_your_logs_into_elasticsearch link we be valid.

This PR needs to be backported to the 3.x and 2.x branches.

[apmmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Start Time: 2021-12-06T20:20:51.688+0000

• Duration: 3 min 30 sec

• Commit: a89e326

🤖 GitHub comments

To re-run your PR in the CI, just comment with:

• /test : Re-trigger the build.

• run module tests for <modules> : Run TAV tests for one or more modules, where <modules> can be either a comma separated list of modules (e.g. memcached,redis) or the string literal ALL to test all modules

• run benchmark tests : Run the benchmark test only.

• run elasticsearch-ci/docs : Re-trigger the docs validation. (use unformatted text in the comment!)

[trentm]

This PR needs to be backported to the 3.x

The 3.x branch gets sync'd to the latest master when we do a release, so the most straightforward thing would be to do a release after this is in.

(Note that earlier today we were discussing perhaps being blocked on doing a release until #2498 is discussed. @bmorelli25 What is the urgency of this? I'm guessing pretty high if builds are broken.)

and 2.x branches.

The 2.x branch isn't maintained anymore. It hasn't had a commit in since 2020-05. It was EOL on 2021-03-19. We can certainly make this change there if that is easiest.

Is there something separate we can do to remove dependence on the "2.x" branch of this repo?

[bmorelli25]

The 3.x branch gets sync'd to the latest master when we do a release, so the most straightforward thing would be to do a release after this is in.

Do you mean that you force push to 3.x when a release is cut? We can certainly release if that's easiest for you. Typically (in the other agents) we'd just backport and then the commit is overwritten on the next release. The choice is yours.

Is there something separate we can do to remove dependence on the "2.x" branch of this repo?

The only other thing would be to remove the 2.x docs from the doc build since they're EOL, but that might produce its own set of problems.

For a bit more context: this kind of thing (fixing old agent links) is typical around release times. Every few releases there's an agent or two that requires us to go back in time and fix things. The problem occurs because of the versioning mismatch between agents and stack. We point to the moving target of "current" which can have negative consequences. Major releases are even worse — I'd expect us to play this game all over again when 8.0 releases.

[trentm]

Do you mean that you force push to 3.x when a release is cut?

We reset the "3.x" branch to master via git branch -f 3.x master && git push origin 3.x.

We can certainly release if that's easiest for you. Typically (in the other agents) we'd just backport and then the commit is overwritten on the next release.

Yah, we could do similar.

The only other thing would be to remove the 2.x docs from the doc build since they're EOL, but that might produce its own set of problems.

Understood. Can we create an issue to track doing that? I think eventually we want to get out of having to worry about the 2.x branch. For this issue, I'll backport the change to the 2.x branch.

[bmorelli25]

Issue opened ⬆️ . I'll merge this PR now. Would you mind taking care of the backport to 3.x as well?

[trentm]

Backported to 3.x: a458109

2.x was handled in #2501