Prep docs for v9 #115375

jakelandis · 2024-10-22T22:53:44Z

This commit prepares the docs for v9.

removes all v8 release notes, highlights, and breaking changes
update v8 files to v9 as place holders for v9 docs
updates references to current (9) and current - 1 (8) where appropriate
ran ./gradlew generateReleaseNotes

Note - Some of this content is generated by ./gradlew generateReleaseNotes and is may not be accurate to v9 only. We will need to manually adjust later. For now just trying to get the big change in.

Also, the REST API doc is showing up in the transient setting migration guide ...I added a fixme to fix later. Again, just trying to get the big change in.

github-actions · 2024-10-22T22:53:56Z

Documentation preview:

✨ Changed pages

elasticsearchmachine · 2024-10-23T21:54:43Z

Pinging @elastic/es-docs (Team:Docs)

jakelandis · 2024-10-23T21:55:37Z

docs/reference/release-notes/highlights.asciidoc


 endif::[]

 // The notable-highlights tag marks entries that
 // should be featured in the Stack Installation and Upgrade Guide:
 // tag::notable-highlights[]

-[discrete]


AFAIK these are all 8.x release highlights.

jakelandis · 2024-10-23T21:58:05Z

docs/reference/rest-api/rest-api-compatibility.asciidoc

-in the migration guide.
+//TODO: figure out how to get the link below to work !
+//For information about specific breaking changes and the impact of requesting
+//compatibility mode. See xref:/docs/reference/migration/migrate_9_0/rest-api-changes.asciidoc[REST API changes] in the migration guide.


@jmikell821 - can you help me figure out how to make this reference work ?

mark-vieira · 2024-10-23T23:33:41Z

Note - I think we will end up fighting with some of the automation for changes targeting both 8.x and 9.0.

I think we've updated things so we don't forward port 8.x release notes to main (9.0). @brianseeders can you confirm/deny this?

leemthompo · 2024-10-24T08:33:33Z

docs/reference/rest-api/rest-api-compatibility.asciidoc

-in the migration guide.
+//TODO: figure out how to get the link below to work !
+//For information about specific breaking changes and the impact of requesting
+//compatibility mode. See xref:/docs/reference/migration/migrate_9_0/rest-api-changes.asciidoc[REST API changes] in the migration guide.


Suggested change

//compatibility mode. See xref:/docs/reference/migration/migrate_9_0/rest-api-changes.asciidoc[REST API changes] in the migration guide.

//compatibility mode. See <<rest-api-changes,REST API changes>> in the migration guide.

driving by here :)

Thanks Liam, I tried that but got:

INFO:build_docs:asciidoctor: WARNING: invalid reference: rest-api-changes

The link is trying :
docs/reference/rest-api/rest-api-compatibility.asciidoc <- from here
docs/reference/migration/migrate_9_0/rest-api-changes.asciidoc <- to here

I only updated the file name and anchor name to be 9 instead of 8. This used to work : <<breaking_80_rest_api_changes, REST API changes>>

This also, does not work: See <<breaking_90_rest_api_changes,REST API changes>>

INFO:build_docs:asciidoctor: WARNING: invalid reference: breaking_90_rest_api_changes

So I assume that maybe I removed some implicit transitive include or something like that (I am pretty clueless with asciidoc)

jakelandis · 2024-10-24T19:08:44Z

Note - I think we will end up fighting with some of the automation for changes targeting both 8.x and 9.0.

Since the process is to start with main and then backport, the automation will create the change logs in main. I'm not sure exactly how those are used to create the release notes, but it will likely require some manual effort to determine if those apply to 9.0.0 only or not. For example, since yesterday the following change logs have been created. There is at least 1 in there that is 9.0.0 only (as determined by the "type: breaking " label).

I will take another look at the recent change logs removed here and preserve them (before i merge this PR) if they have "type: breaking", but it will be very ~~difficult~~ time consuming without automation support to know based on the information in the change log if it is a 9.0.0 only or not change.

EDIT: on second thought, there is no need to remove the change logs now, so I will leave them alone (reverted the removal)

This reverts commit 0cd8cb2.

jakelandis · 2024-10-24T20:32:50Z

pull back to draft since I just realized this competes with #114154 that does the same thing (but slightly better).

jakelandis · 2024-10-25T18:30:16Z

Closing this as dupcliate of #114154

jakelandis · 2024-10-30T23:11:04Z

re-opening since #114154 was closed

jakelandis · 2024-10-30T23:15:34Z

@leemthompo - could you please review. the docs don't need to be perfect for now, but we need a place to start collecting the information.

leemthompo

Couple questions, happy to approve if need unblocking to move forward, just re-ping :)

leemthompo · 2024-10-31T09:26:46Z

docs/reference/migration/migrate_9_0.asciidoc

@@ -0,0 +1,314 @@
+[[migrating-9.0]]
+== Migrating to 9.0


@jakelandis there's a lot of stuff in here that's already in 8.x, is that going to be more or less confusing to clean up now versus in a follow-up?

We will end fighting abit with the automation. So even if i clean this up now, it will just come back the next time someone generates the release notes. I think we will need to fix this is in the automation, or just go manual, or something in-between. I would prefer to address in a follow up since the changes here are intended to mechanical. I will add a comment to this file (and others) something to the effect that this is generated.

I updated this PR with a comment for these generated file that links to an internal issue for us to follow up with. I also commented out the content created by the automation. While no one is probably looking at the v9 release notes (it's not released yet) it is better to have no information than wrong information.

leemthompo · 2024-10-31T09:28:27Z

docs/reference/release-notes/highlights.asciidoc

-[chapter]
 [[release-highlights]]
-= What's new in {minor-version}
+== What's new in {minor-version}


I presume the removal of [chapter] and the deepening of sub-headings was created by automation?

We recently changed the IA of the left-nav and we don't want to lose these.

tl;dr we need the chapter id and the headings here should start at H2

yeah, this was created by automation. If if fix it now, it will come back the next time some generates the release notes. I will add a comment to this effect to this file too and will address in a follow up.

…issue

leemthompo · 2024-10-31T13:47:49Z

docs/reference/migration/migrate_9_0.asciidoc

@@ -1,3 +1,6 @@
+// THIS IS A GENERATED FILE. DO NOT EDIT DIRECTLY.


This commit prepares the documentation for version 9. Some of the automation generates docs that are not correct for version 9. The content has been commented out with a reference to an internal issue for us to address before this documentation is used.

prep docs for v9

a1b8f5d

elasticsearchmachine added the v9.0.0 label Oct 22, 2024

jakelandis added 4 commits October 23, 2024 15:45

Merge remote-tracking branch 'upstream/main' into docs_v9

ae4d210

remove change logs

0cd8cb2

fix todo to link to transient settings guide

37a0a3e

i hate asciidoc

16be71b

jakelandis added the >docs General docs changes label Oct 23, 2024

jakelandis requested review from a team and jmikell821 October 23, 2024 21:54

jakelandis marked this pull request as ready for review October 23, 2024 21:54

elasticsearchmachine added the Team:Docs Meta label for docs team label Oct 23, 2024

jakelandis commented Oct 23, 2024

View reviewed changes

leemthompo reviewed Oct 24, 2024

View reviewed changes

Merge remote-tracking branch 'upstream/main' into docs_v9

863e95c

Revert "remove change logs"

1ff4a86

This reverts commit 0cd8cb2.

jakelandis marked this pull request as draft October 24, 2024 20:32

jakelandis closed this Oct 25, 2024

updates

5f40741

jakelandis reopened this Oct 30, 2024

jakelandis marked this pull request as ready for review October 30, 2024 23:14

leemthompo reviewed Oct 31, 2024

View reviewed changes

re-run automation and comment it out with a reference to an internal …

0f24128

…issue

leemthompo approved these changes Oct 31, 2024

View reviewed changes

leemthompo reviewed Oct 31, 2024

View reviewed changes

docs/reference/migration/migrate_9_0.asciidoc

@@ -1,3 +1,6 @@

// THIS IS A GENERATED FILE. DO NOT EDIT DIRECTLY.

Copy link

Contributor

leemthompo Oct 31, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️

Merge remote-tracking branch 'upstream/main' into docs_v9

550fbf5

jakelandis merged commit aaf7a3e into elastic:main Oct 31, 2024
5 checks passed

This was referenced Nov 21, 2024

[DOCS] Remove broken migration guide link #117293

Merged

[DOCS] Re-add transient settings migration guide #117299

Closed

	//compatibility mode. See xref:/docs/reference/migration/migrate_9_0/rest-api-changes.asciidoc[REST API changes] in the migration guide.
	//compatibility mode. See <<rest-api-changes,REST API changes>> in the migration guide.

		@@ -1,3 +1,6 @@
		// THIS IS A GENERATED FILE. DO NOT EDIT DIRECTLY.

Prep docs for v9 #115375

Prep docs for v9 #115375

Uh oh!

Conversation

jakelandis commented Oct 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 22, 2024

Uh oh!

elasticsearchmachine commented Oct 23, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mark-vieira commented Oct 23, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakelandis Oct 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakelandis commented Oct 24, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jakelandis commented Oct 24, 2024

Uh oh!

jakelandis commented Oct 25, 2024

Uh oh!

jakelandis commented Oct 30, 2024

Uh oh!

jakelandis commented Oct 30, 2024

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakelandis Oct 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jakelandis commented Oct 22, 2024 •

edited

Loading

mark-vieira commented Oct 23, 2024 •

edited

Loading

jakelandis Oct 24, 2024 •

edited

Loading

jakelandis commented Oct 24, 2024 •

edited

Loading

jakelandis Oct 31, 2024 •

edited

Loading