Update for a coming apm-agent-nodejs 4.x stream

[trentm]

This also drops hosting the ancient 0.x version of the apm-agent-nodejs docs.

[bmorelli25]

Ah, the 4.x branch doesn't exist yet. The docs ci check will fail until it does.

17:52:06 INFO:build_docs:Error executing: git archive --format=tar -o /tmp/docsbuild/iKrWzqBjLA/apm-agent-nodejs/.temp_git_archive.tar 4.x docs in GIT_DIR /docs_build/.repos/apm-agent-nodejs.git

[trentm]

Ah, the 4.x branch doesn't exist yet.

Yah, I'll have one in a little bit. I couldn't create a temporary one from our "dev/4.x" branch because it has merge commits that our branch protections disallow.

[trentm]

Yah, I'll have one in a little bit.

That took more than a little bit. There is a 4.x branch now.

[trentm]

@elasticmachine, run elasticsearch-ci/docs

[bmorelli25]

I pushed an update that changes how some stack versions will link to the Node.js docs. In addition, we'll need to update the Node.js docs version for a few older stack versions:

docs/shared/versions/stack/6.3.asciidoc

Line 21 in 303232e

:apm-node-branch: 1.x

docs/shared/versions/stack/6.4.asciidoc

Line 21 in 303232e

:apm-node-branch: 1.x

docs/shared/versions/stack/6.5.asciidoc

Line 23 in 303232e

:apm-node-branch: 2.x

Can these be bumped to 3.x? If they remain unchanged, the build will fail with the removal of the 1.x and 2.x branches.

[trentm]

Can these be bumped to 3.x?

Hrm, I'm guessing not. Both 3.x and 4.x of the Node.js APM agent are documented to only support back to APM Server v6.6.

Do you know if we need to have links to online docs for versions of the APM agents for 6.3, 6.4, 6.5? Do we still support those versions of the stack?

In any case, this change is not an appropriate one to have a cascade of dropping docs for earlier version of the stack, so we could put the 1.x and 2.x docs back in if that is easiest. (Though they are obsolete and completely unsupported.)

What is easiest here?

[trentm]

I guess we could drop the 0.x docs at least.

[trentm]

@bmorelli25 Also, what do you think about pointing to apm-node-branch 4.x for the 7.x versions of the stack as well?

[trentm]

Also the 2.x here seems wrong:

shared/versions/stack/7.4.asciidoc
28::apm-node-branch:       3.x

shared/versions/stack/7.5.asciidoc
28::apm-node-branch:       2.x

[bmorelli25]

@bmorelli25 Also, what do you think about pointing to apm-node-branch 4.x for the 7.x versions of the stack as well?

Yes, definitely. I wasn't sure on compatibility when I pushed my original commit.

Both 3.x and 4.x of the Node.js APM agent are documented to only support back to APM Server v6.6.

Should we bring 4.x all the way back to 6.6 then?

Do you know if we need to have links to online docs for versions of the APM agents for 6.3, 6.4, 6.5? Do we still support those versions of the stack?

We do not support these versions of the stack anymore, but we do have to continue publishing documentation for them. Unfortunately, our doc build doesn't support version-specific link checking, so we also have to maintain links between older versions.

I guess we could drop the 0.x docs at least.

Agreed.

In any case, this change is not an appropriate one to have a cascade of dropping docs for earlier version of the stack, so we could put the 1.x and 2.x docs back in if that is easiest. (Though they are obsolete and completely unsupported.)

Is 2.x supported by 6.3 and 6.4? If so, we could also get rid of v1.x of the agent.

[trentm]

Should we bring 4.x all the way back to 6.6 then?

Yes.

Is 2.x supported by 6.3 and 6.4? If so, we could also get rid of v1.x of the agent.

https://www.elastic.co/guide/en/apm/agent/nodejs/2.x/supported-technologies.html#elastic-stack-compatibility
says "This agent is compatible with APM Server v6.5 and above. For support for previous releases of the APM Server, use version 1.x of the agent."

... so I think we are stuck with publishing the 1.x docs as well for 6.4 and below.

https://www.elastic.co/guide/en/apm/agent/nodejs/1.x/compatibility.html#elastic-stack-compatibility says "Version 1.x of the agent is compatible with APM Server v6.2 to v6.4."

[bmorelli25]

Pushing a change to fix the build...

[bmorelli25]

Nice. The build succeeded. Here's a preview link for the new 4.x docs.

[trentm]

The build succeeded.

Nice, thanks. So I should take this out of draft and get it merged right after we've done the first 4.x release and updated our "4.x" branch, right?

[bmorelli25]

That's correct.

1. Take out of draft
2. I'll approve
3. Release the 4.x version
4. Merge this PR
5. Ask @bmorelli25 to kick off a full rebuild of the Elastic documentation site in Jenkins (takes ~ 70 mins)
6. Docs are live!

[bmorelli25]

🚢