docs: update RELEASE.md #12983

endorama · 2024-04-17T08:21:16Z

This PR aims at refreshing the release documentation for apm-server. I'll use it to collect changes as I go through the release process as release manager.

Closes #12864

release notes are no more present in docs/release_notes.asciidoc

mergify · 2024-04-17T08:21:59Z

This pull request does not have a backport label. Could you fix it @endorama? 🙏
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.

NOTE: backport-skip has been added to this pull request.

endorama · 2024-04-17T08:22:51Z

dev_docs/RELEASES.md

@@ -17,9 +17,9 @@ For patch releases, only the version on the existing major and minor version bra
  * Review existing [changelogs/head](https://github.com/elastic/apm-server/tree/main/changelogs/head.asciidoc) to ensure all relevant notes have been added.


Question: how do I make sure there are no PR to be merged? I checked all PRs that don't have a backport-skip label applied through this search. If that is appropriate I would add it to the documentation to help streamline this step.

dev_docs/RELEASES.md

Guide the release manager to leverage available automations instead of performing manual actions.

carsonip

I think it is missing docs release process. It used to be done by docs team but it is now our responsibility to do so. Can you figure out at which stage that should happen and update the docs, and give an example?

dev_docs/RELEASES.md

carsonip · 2024-05-08T15:16:28Z

dev_docs/RELEASES.md

-    to create an overview over the PRs that need testing. For example, [test plan link for 8.3.0](https://github.com/elastic/apm-server/issues?q=label%3Atest-plan+is%3Aclosed+label%3Av8.3.0).
-  * Add other test cases that require manual testing, such as test scenarios on ESS, that are not covered by automated tests or
-    OS compatibility smoke tests for supporting new operating systems.
+  Create a github issue for testing the release branch ([use the GitHub issue `test plan` template](https://github.com/elastic/apm-server/issues/new?assignees=&labels=test-plan&projects=&template=test-plan.md)), It should contain:


What about including a recent example?

Are you referring to the link on line 41 or 43? This link brings you to the new issue view with the test-plan template selected (there is a separate PR for updating the test plan). On line 43 instead there is a link to a 8.3.0 test plan, which looks like what you would like to see updated?

I'd like an new link to a recent test plan issue, in addition to the existing link to the issue view with filtered with test-plan label

Co-authored-by: Carson Ip <carsonip@users.noreply.github.com>

endorama · 2024-05-08T15:31:50Z

@carsonip thanks for pointing to the doc release. I'll dig into that.

bmorelli25 · 2024-05-08T16:04:12Z

dev_docs/RELEASES.md

+  * ensure all relevant backport PRs are merged. We use backport labels on PRs and automation to ensure labels are set.



The release note process was a bit out of date. I've updated it in this suggestion:

Suggested change

* ensure all relevant backport PRs are merged. We use backport labels on PRs and automation to ensure labels are set.

* Ensure all relevant backport PRs are merged. Backport PRs are automatically opened based on `backport-X.Y` labels added to PRs opened against `main`.

* Add release notes

* Review the [changelogs/head](https://github.com/elastic/apm-server/tree/main/changelogs/head.asciidoc) file and move all relevant release notes from `head.asciidoc` to `release_version.asciidoc. If changes do not apply to the version being released, keep them in the `changelogs/head.asciidoc` file.

* Minor version:

Create a new changelog file from [`changelogs/head.asciidoc`](https://github.com/elastic/apm-server/blob/main/changelogs/head.asciidoc)

Don't forget to `include` and link to the new file in [main changelog](https://github.com/elastic/apm-server/blob/main/CHANGELOG.asciidoc) file and the [release notes](https://github.com/elastic/apm-server/blob/main/docs/release-notes.asciidoc) file. [(Sample PR)](https://github.com/elastic/apm-server/pull/7956/files)

* Patch version:

Add a new section to existing release notes. ([Sample PR](https://github.com/elastic/apm-server/pull/8313/files))

* Add `@elastic/obs-docs` as a reviewer.

Thanks for the suggestion. I'm confused about lines 14-21 though: we have 2 automation that perform what is described there and we are documenting them on line 18-22 of the new RELEASES.md. May you share the rationale for adding that part again?

Looks like it would've helped if I had actually read the entire file 😵‍💫

So the manual process has been replaced with an automated one.

I think it is missing docs release process. It used to be done by docs team but it is now our responsibility to do so. Can you figure out at which stage that should happen and update the docs, and give an example?

@carsonip I'm not sure what's missing then

Thanks @bmorelli25! Then I will consider this conversation resolved (but won't do it in GitHub for future reference).

Patch release automation does not include changelog changes. It has to be done in coordination with docs release manually. See https://github.com/elastic/dev/issues/2485 (private) and #12680

carsonip · 2024-05-13T11:17:23Z

dev_docs/RELEASES.md

+  * ensure all relevant backport PRs are merged. We use backport labels on PRs and automation to ensure labels are set.



Patch release automation does not include changelog changes. It has to be done in coordination with docs release manually. See https://github.com/elastic/dev/issues/2485 (private) and #12680

carsonip · 2024-05-13T11:18:09Z

dev_docs/RELEASES.md

-
-  The release manager will ping the teams, but you can already prepare this in advance on the day after Feature Freeze.
+* Trigger release workflow manually
+  * For **patch releases**: run the [`run-patch-release`](https://github.com/elastic/apm-server/actions/workflows/run-patch-release.yml) workflow.


Describe what patch release automation does. It does not include changelog changes. It updates some versions iirc.

For patch release notes we could add something like this:

For patch releases, release notes must be manually added:

Add a new section to the existing release notes file (Sample PR).

Review the changelogs/head file and move all relevant release notes from head.asciidoc to release_version.asciidoc. If changes do not apply to the version being released, keep them in the head.asciidoc file.

Review the commits in the release to ensure all changes are reflected in the release notes.

Add your PR to the documentation release issue (Sample Issue).

remove reference to release notes

067846a

release notes are no more present in docs/release_notes.asciidoc

mergify bot added the backport-skip Skip notification from the automated backport with mergify label Apr 17, 2024

endorama commented Apr 17, 2024

View reviewed changes

dev_docs/RELEASES.md Outdated Show resolved Hide resolved

carsonip self-requested a review April 17, 2024 08:51

Update release instructions including automation

8ff3ad1

Guide the release manager to leverage available automations instead of performing manual actions.

endorama mentioned this pull request Apr 17, 2024

Document release process with the automation workflow #12864

Open

Update RELEASES.md

b86b39d

endorama marked this pull request as ready for review May 2, 2024 10:37

endorama requested a review from a team as a code owner May 2, 2024 10:37

Merge branch 'main' into endorama-patch-1

636da21

kruskall previously approved these changes May 8, 2024

View reviewed changes

Merge branch 'main' into endorama-patch-1

49ae368

carsonip reviewed May 8, 2024

View reviewed changes

Apply suggestions from code review

e1aa910

Co-authored-by: Carson Ip <carsonip@users.noreply.github.com>

endorama dismissed kruskall’s stale review via e1aa910 May 8, 2024 15:30

bmorelli25 reviewed May 8, 2024

View reviewed changes

carsonip reviewed May 13, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update RELEASE.md #12983

docs: update RELEASE.md #12983

endorama commented Apr 17, 2024 •

edited by carsonip

mergify bot commented Apr 17, 2024

endorama Apr 17, 2024

carsonip left a comment

carsonip May 8, 2024

endorama May 8, 2024

carsonip May 8, 2024

endorama commented May 8, 2024

bmorelli25 May 8, 2024 •

edited

endorama May 9, 2024

bmorelli25 May 9, 2024

bmorelli25 May 9, 2024

endorama May 13, 2024

carsonip May 13, 2024 •

edited

carsonip May 13, 2024 •

edited

carsonip May 13, 2024

bmorelli25 May 13, 2024

		@@ -17,9 +17,9 @@ For patch releases, only the version on the existing major and minor version bra
		* Review existing [changelogs/head](https://github.com/elastic/apm-server/tree/main/changelogs/head.asciidoc) to ensure all relevant notes have been added.

		* ensure all relevant backport PRs are merged. We use backport labels on PRs and automation to ensure labels are set.

-  * ensure all relevant backport PRs are merged. We use backport labels on PRs and automation to ensure labels are set.
+  * Ensure all relevant backport PRs are merged. Backport PRs are automatically opened based on `backport-X.Y` labels added to PRs opened against `main`.
+  * Add release notes
+    * Review the [changelogs/head](https://github.com/elastic/apm-server/tree/main/changelogs/head.asciidoc) file and move all relevant release notes from `head.asciidoc` to `release_version.asciidoc. If changes do not apply to the version being released, keep them in the `changelogs/head.asciidoc` file.
+      * Minor version:
+        Create a new changelog file from [`changelogs/head.asciidoc`](https://github.com/elastic/apm-server/blob/main/changelogs/head.asciidoc)
+        Don't forget to `include` and link to the new file in [main changelog](https://github.com/elastic/apm-server/blob/main/CHANGELOG.asciidoc) file and the [release notes](https://github.com/elastic/apm-server/blob/main/docs/release-notes.asciidoc) file. [(Sample PR)](https://github.com/elastic/apm-server/pull/7956/files)
+      * Patch version:
+        Add a new section to existing release notes. ([Sample PR](https://github.com/elastic/apm-server/pull/8313/files))
+    * Add `@elastic/obs-docs` as a reviewer.

docs: update RELEASE.md #12983

Are you sure you want to change the base?

docs: update RELEASE.md #12983

Conversation

endorama commented Apr 17, 2024 • edited by carsonip

mergify bot commented Apr 17, 2024

Choose a reason for hiding this comment

carsonip left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

endorama commented May 8, 2024

bmorelli25 May 8, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carsonip May 13, 2024 • edited

Choose a reason for hiding this comment

carsonip May 13, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

endorama commented Apr 17, 2024 •

edited by carsonip

bmorelli25 May 8, 2024 •

edited

carsonip May 13, 2024 •

edited

carsonip May 13, 2024 •

edited