[DOCS] Cleans up release notes #4524
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR cleans up the release notes for Elastic Docs v3 by updating heading titles, navigation metadata, and dropdown IDs to improve consistency and clarity.
- Updated navigation titles and placeholders to standardize documentation references.
- Revised dropdown formats and link references across breaking changes, known issues, and release notes.
- Updated the table of contents and the upgrading guide to reflect the new file structure.
Reviewed Changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/release-notes/breaking-changes.md | Updated headings, navigation title, and structured dropdowns. |
| docs/release-notes/known-issues.md | Standardized heading and dropdown content for known issues. |
| docs/release-notes/release-notes.md | Refactored release note sections with updated dropdown IDs and headings. |
| docs/release-notes/toc.yml | Adjusted file ordering in the table of contents. |
| docs/reference/upgrading.md | Updated the link to the release notes page. |
Comments suppressed due to low confidence (1)
docs/release-notes/release-notes.md:250
- Typo detected: 'propertly' should be corrected to 'properly'.
"next" will propertly disable all Next.js instrumentation. ([#3658](https://github.com/elastic/apm-agent-nodejs/pull/3658))
| @@ -9,7 +9,7 @@ The Elastic APM Node.js Agent uses [semantic versioning](https://semver.org/), a | |||
|
|
|||
| Before upgrading the agent, be sure to review the: | |||
|
|
|||
| * [Node.js APM Agent release notes](/release-notes/index.md) | |||
| * [Node.js APM Agent release notes](/release-notes/release-notes.md) | |||
There was a problem hiding this comment.
A URL with "release-notes/release-notes" duplicated is odd.
There was a problem hiding this comment.
I agree. @KOTungseth can we use /release-notes/index.md?
There was a problem hiding this comment.
Can the navigation_title be changed here so it says "Release Notes" in the toc (or however that can be done). Currently:
| ## 4.11.1 [4-11-1] | ||
| ## 4.11.1 [elastic-apm-nodejs-agent-4111-release-notes] |
There was a problem hiding this comment.
@KOTungseth @colleenmcginnis There is some churn here between the anchors names you are both using.
There was a problem hiding this comment.
@KOTungseth do we need these long IDs now that IDs only have to be unique to each Markdown file? It should be sufficient to link to apm-agent-nodejs://release-notes/index.md#4-11-1 right?
There was a problem hiding this comment.
I've also had devs ask if we can use - between major, minor, and patch versions for clarity (example).
| * Changes to cloud metadata collection for Google Cloud (GCP). Most notably the `cloud.project.id` field is now the `project-id` from [https://cloud.google.com/compute/docs/metadata/default-metadata-values#project_metadata](https://cloud.google.com/compute/docs/metadata/default-metadata-values#project_metadata) rather than the `numeric-project-id`. This matches the value produced by Elastic Beats (like filebeat). [#3614](https://github.com/elastic/apm-agent-nodejs/issues/3614) | ||
|
|
||
| ## 4.0.0 [4-0-0] | ||
| ## 4.0.0 [elastic-apm-nodejs-agent-440-release-notes] |
There was a problem hiding this comment.
Is this 440 error in the anchor name the reason that the 4.0.0 entry in the "On this page" TOC in the wrong place?
See https://docs-v3-preview.elastic.dev/elastic/apm-agent-nodejs/pull/4524/release-notes/release-notes
| ::::{dropdown} Removes support for next@11 |
There was a problem hiding this comment.
(Sorry to be negative.) I really don't like the pattern of having a disclosure to click to get the context on each separate breaking change. Why should a user have to click open every one of these to have to get (and search) the context. For example, in the breaking changes for 4.0.0 there are three changes that impact the startTransaction() API. However, to find them you have to click open everything before searching.
Was there a reason for the added dropdown UI here?
Cleans up the release notes for Elastic Docs v3.
Checklist
docs/release-notes/index.md