[docs] Add release notes to documentation

[bmorelli25]

For #1427.

This PR adds release notes to the Elastic documentation for the Node.js APM Agent. Additional information and discussion is in elastic/apm#132.

To be merged concurrently with elastic/docs#1267.

---

Brandon's notes for future PRs:

// regex for md --> asciidoc links
\(\[\#(\d+)\]\(.+\)\)
{pull}$1[#$1]

// regex for adding anchor ids
===\s(\d+\.\d+\.\d+)
[[release-notes-$1]]\n=== $1

// regex for generating release notes links
(\d\.\d*\.\d*)(.*)
* <<release-notes-$1>>

// regex for md --> asciidoc links
\[(.*)\]\((.*)\)
$2[$1]

[Qard]

Left a few comments. Also, what do you think of breaking the changelog up into a page or section per-major, the we could easily link to a point that shows the latest of whatever major version. So someone might want to see what the latest v2 is and it'd suck to have to scroll past all the v3 stuff to get to it.

[bmorelli25]

Thanks @Qard! I've implemented your recommendations. Follow up question. All of our stack docs build release notes to one page for each minor. The subpages then link to release notes for each bug fix. Example here: https://www.elastic.co/guide/en/apm/server/current/release-notes.html.

As-is, these release notes match that format. One thing I've noticed is that there are a lot of minor releases. Perhaps building the release notes to different pages isn't the best idea. Do you prefer the release notes are on their own indiviudal pages? Or are sorted by major? Here are some screenshots for reference:

Main page:

2.x page:

2.x.x page:

[Qard]

Ah, so I wasn't thinking of having a single page for each release just for each major range, so everything in 2.x would be on one page and everything in 3.x would be on another page. We could probably put it all in one page with headers splitting each section, just thinking that would get really long fast. A page per major seemed like a good balance to me.

[bmorelli25]

Cool! I agree that's probably the best approach. Updated this PR so that each major has its own page for release notes.

[bmorelli25]

@nik9000 Can you see what I'm doing wrong here? Locally, this builds fine. I can interact with the preview and everything. It keeps failing ci though:

18:55:00 INFO:build_docs:asciidoctor: ERROR: release-notes.asciidoc: line 12: include file not found: /tmp/docsbuild/3GOHVMW8yP/apm-agent-nodejs/CHANGELOG.asciidoc
18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-3.x
18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-2.x
18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-1.x
18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-0.x
18:55:00 INFO:build_docs:
18:55:00 INFO:build_docs:Child exited with 255 at lib/ES/Util.pm line 903.

It can't find the included file, but I'm not sure why. The include is here: https://github.com/elastic/apm-agent-nodejs/pull/1435/files#diff-fd18ff3bf5717a4631f4bc2a22a58e31R11

[nik9000]

The changelog probably isn't in conf.yaml. I'm on mobile and can't confirm it now though.

…

On Mon, Oct 7, 2019, 22:03 Brandon Morelli ***@***.***> wrote: @nik9000 <https://github.com/nik9000> Can you see what I'm doing wrong here? Locally, this builds fine. I can interact with the preview and everything. It keeps failing ci though: 18:55:00 INFO:build_docs:asciidoctor: ERROR: release-notes.asciidoc: line 12: include file not found: /tmp/docsbuild/3GOHVMW8yP/apm-agent-nodejs/CHANGELOG.asciidoc 18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-3.x 18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-2.x 18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-1.x 18:55:00 INFO:build_docs:asciidoctor: WARNING: invalid reference: release-notes-0.x 18:55:00 INFO:build_docs: 18:55:00 INFO:build_docs:Child exited with 255 at lib/ES/Util.pm line 903. It can't find the included file, but I'm not sure why. The include is here: https://github.com/elastic/apm-agent-nodejs/pull/1435/files#diff-fd18ff3bf5717a4631f4bc2a22a58e31R11 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1435?email_source=notifications&email_token=AABUXIU5K4QG2UJKRCGTTIDQNPS5TA5CNFSM4I6HQMXKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEASMEMA#issuecomment-539279920>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABUXIXV4RKOSIN526I6OBLQNPS5TANCNFSM4I6HQMXA> .

[bmorelli25]

@nik9000 Woah, you're right. I see the changelog included for apm-server in conf.yaml, but not for this repo. I never knew that was a thing. I think I know how to fix this now. Thank you!

[Qard]

LGTM. I'd also like to backport this to 2.x, which I think shouldn't be too difficult as we'd just need to delete the 3.x section in CHANGELOG.asciidoc and the link in docs/release-notes.asciidoc.