[docs] Migrate docs from AsciiDoc to Markdown

[colleenmcginnis]

Migrate docs from AsciiDoc to Markdown. The preview can be built after #16081 is merged.

Notes:

• I deleted all the AsciiDoc files. Our AsciiDoc build system no longer pulls from main so any changes to the 8.x changelog files should target the 8.x and specific version branches instead (for example, 8.18). Let me know if you anticipate any problems with this approach.
• I consolidated information in the AsciiDoc HEAD changelog file, the AsciiDoc 9.0 changelog, and the Markdown release note related files from docs-content (release notes, known issues, breaking changes, deprecations). @KOTungseth I did my best to follow the format introduced by the template text at the top of each file (except for individual known issue sections since I wasn't sure if we should keep the 8.x known issues on main).
• I believe the idea is that all the content related to release notes should be added to these four files instead of individual files for each version. We'll also always be publishing directly from main (at least in the short term). @KOTungseth can correct me if I'm wrong!
• I also created a CHANGELOG.md file in the top level of this repo to help users find release notes from the GitHub repo, but we don't need it if you don't think it's necessary.
• When you look at the PR preview (after [docs] Add the new docs CI checks #16081 is merged), you'll notice that the text in the left side navigation looks incorrect. This is expected for now. It will be resolved when we're able to bundle pages from all repos together (Strategy for nav headings that make sense in one context but not in another docs-builder#621).
• Once we merge this, I will remove the APM release note related pages from the docs-content repo.

[mergify]

This pull request does not have a backport label. Could you fix it @colleenmcginnis? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-7.17 is the label to automatically backport to the 7.17 branch.
• backport-8./d is the label to automatically backport to the 8./d branch. /d is the digit.
• backport-9./d is the label to automatically backport to the 9./d branch. /d is the digit.
• backport-8.x is the label to automatically backport to the 8.x branch.
• backport-active-all is the label that automatically backports to all active branches.
• backport-active-8 is the label that automatically backports to all active minor branches for the 8 major.
• backport-active-9 is the label that automatically backports to all active minor branches for the 9 major.

[carsonip]

Q about the workflow. Are the docs build per-branch, like how we did in the past?

e.g. if we have a change that goes into 9.0.100 which is a version released later than 9.1.0. Should we add the changelog directly to main under section 9.0.100? Does it matter if we backport the changelog?

[carsonip]

Suggested change

	% To learn how to upgrade, check out <uprade docs>.
	% To learn how to upgrade, check out <upgrade docs>.

I see this typo in docs-content as well. Not sure if it is widespread

[carsonip]

cc 9.0 release manager @inge4pres

[carsonip]

thanks for bringing this in from elastic/docs-content#647 already!

[colleenmcginnis]

e.g. if we have a change that goes into 9.0.100 which is a version released later than 9.1.0. Should we add the changelog directly to main under section 9.0.100? Does it matter if we backport the changelog?

@KOTungseth can you advise? Should they be adding to a Next section in the release notes files on main? Or should they do something else? And should the sections go in date order or in version number order?

[colleenmcginnis]

Here are some clarifications:

• We're only building from main for the foreseeable future. You can add release notes for an upcoming unreleased version to the Next version section, which is currently commented out.
• Sections in the release notes should be in version order. So in your example: a change that goes into 9.0.100, which is a version released later than 9.1.0, you should add the entry directly to main under section 9.0.100, which should be alongside other 9.0 releases.
• Since we're only building from main, you don't have to backport, but you can backport release note edits if it makes it easier for you to backport other changes without conflicts.

Let me know if you have additional questions!

[colleenmcginnis]

This is ready for review! You can view the preview by clicking the "View deployment" button:

If you're interested in building a preview locally, you can follow the instructions here: https://elastic.github.io/docs-builder/contribute/locally/.

Note: The release notes section at the bottom of the table of contents looks strange, but that's expected at this stage (see elastic/docs-builder#621).

Let me know if you have any more questions after you take a look!

[carsonip]

lgtm, thanks!

[endorama]

@carsonip we also need to update our release automations to account for these changes? Have we discussed this?

[carsonip]

@carsonip we also need to update our release automations to account for these changes? Have we discussed this?

Nice catch. It was not discussed, and there are still a lot of release automation on asciidoc. https://github.com/elastic/apm-server/blob/main/release.mk . I've created #16181 for it.