From 8c5fe6499db6645b48798329d98c39a7aeaace52 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 15:30:48 -0800 Subject: [PATCH 1/3] Update move-ref-docs.md --- docs/migration/guide/move-ref-docs.md | 38 ++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index b5c9933c2..978a262e5 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -4,9 +4,11 @@ navigation_title: Move reference docs # Move reference docs from Asciidocalypse -:::{note} -This guide is only for technical writers tasked with moving content out of `elastic/asciidocalypse`. -::: +This page has three parts: + +1. [How reference content works in V3](#how-reference-content-works-in-v3) --> potentially interesting for contributors wanting to understand how PR previews and full website builds differ +2. [How to Move Reference Content](#how-to-move-reference-content) --> not really important anymore as the process has been automated +3. [How to manage moved reference content](#how-to-manage-moved-reference-content) --> important for writers who have been assigned to help get reference content merged ## How reference content works in V3 @@ -71,6 +73,10 @@ For the **full Elastic.co/docs site**, the assembler references the individual c ## How to Move Reference Content +:::{note} +The moving of reference content has been automated. These docs will live on in the short term as a point of reference. +::: + The steps below explain how to move reference content. You can also take a look at our [sample PR](https://github.com/elastic/apm-agent-android/pull/398), which has specific commits to illustrate some of the steps below. ### Step 1: Delete Existing AsciiDoc Files @@ -175,3 +181,29 @@ Once everything is confirmed working, merge the pull request. ### Step 6: Update the Tracking Issue Update [issue#130](https://github.com/elastic/docs-eng-team/issues/130) to reflect the completed migration. + +## How to manage moved reference content + +You've been assigned to a repo in [issue#130](https://github.com/elastic/docs-eng-team/issues/130). Now what? + +The good news is all of the PRs have been opened for you. For each repository, there are two PRs that have been opened: + +1. A PR that adds the GH actions for build previews ([example](https://github.com/elastic/ecs-logging/pull/85)) +2. A PR that removes asciidoc content and adds md content ([example](https://github.com/elastic/ecs-logging/pull/84)) + +In an ideal world, your job is to work with codeowners and repo admins to: + +1. Get the first PR merged +2. Merge main into the second PR and get it merged + +Doing this in two PRs ensures we can merge content with clean CI the first time. + +We recognize that some repositories are harder to work in than others. If this is the case, you can cherry pick the commits into a single PR and work with codeowners to get one PR merged. The downside of this approach is that we won't be sure if CI passes until the content is merged. We trust your judgement. Do what is right for your scenario. + +### Considerations + +Make sure to consider the following things: + +* Are these PRs deleting the right content? Is any of the content in the docs dir used, for example, for internal docs that shouldn't be deleted? +* Is the right content being moved? +* Are tests passing? If not, what needs to be done to get the content into a mergable state? From 0948564dba0ab038503a2fc43a8c3812e57a73ed Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 15:43:46 -0800 Subject: [PATCH 2/3] Update move-ref-docs.md --- docs/migration/guide/move-ref-docs.md | 49 ++++++++++++++++----------- 1 file changed, 30 insertions(+), 19 deletions(-) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 978a262e5..5bbc3e03e 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -4,11 +4,13 @@ navigation_title: Move reference docs # Move reference docs from Asciidocalypse -This page has three parts: +This page is divided into three sections: -1. [How reference content works in V3](#how-reference-content-works-in-v3) --> potentially interesting for contributors wanting to understand how PR previews and full website builds differ -2. [How to Move Reference Content](#how-to-move-reference-content) --> not really important anymore as the process has been automated -3. [How to manage moved reference content](#how-to-manage-moved-reference-content) --> important for writers who have been assigned to help get reference content merged +1. [How Reference Content Works in V3](#how-reference-content-works-in-v3) – Useful for contributors who want to understand the difference between PR previews and full website builds. +2. [How to Move Reference Content](#how-to-move-reference-content) – No longer relevant, as the process has been automated. +3. [How to Manage Moved Reference Content](#how-to-manage-moved-reference-content) – Important for writers responsible for merging reference content. + +Jump to the relevant section based on your needs. ## How reference content works in V3 @@ -182,28 +184,37 @@ Once everything is confirmed working, merge the pull request. Update [issue#130](https://github.com/elastic/docs-eng-team/issues/130) to reflect the completed migration. -## How to manage moved reference content +## Managing Moved Reference Content + +You've been assigned to a repository in [issue #130](https://github.com/elastic/docs-eng-team/issues/130). Now what? + +The good news: all necessary PRs have already been opened for you. Each repository has two PRs: + +1. A PR that adds GitHub Actions for build previews ([example](https://github.com/elastic/ecs-logging/pull/85)). +2. A PR that removes AsciiDoc content and adds Markdown content ([example](https://github.com/elastic/ecs-logging/pull/84)). + +### Your Role -You've been assigned to a repo in [issue#130](https://github.com/elastic/docs-eng-team/issues/130). Now what? +Ideally, your job is to work with codeowners and repo admins to: -The good news is all of the PRs have been opened for you. For each repository, there are two PRs that have been opened: +1. **Get the first PR merged** (to ensure previews work). +2. **Merge `main` into the second PR and get it merged**. -1. A PR that adds the GH actions for build previews ([example](https://github.com/elastic/ecs-logging/pull/85)) -2. A PR that removes asciidoc content and adds md content ([example](https://github.com/elastic/ecs-logging/pull/84)) +Splitting this into two PRs ensures that content is merged with a clean CI pass on the first attempt. -In an ideal world, your job is to work with codeowners and repo admins to: +### Alternative Approach -1. Get the first PR merged -2. Merge main into the second PR and get it merged +Some repositories may be more challenging to work with. If needed, you can cherry-pick the commits into a single PR and collaborate with codeowners to get it merged. -Doing this in two PRs ensures we can merge content with clean CI the first time. +**Downside:** We won't know if CI passes until after merging. +**Use your judgment**—choose the best approach for your situation. -We recognize that some repositories are harder to work in than others. If this is the case, you can cherry pick the commits into a single PR and work with codeowners to get one PR merged. The downside of this approach is that we won't be sure if CI passes until the content is merged. We trust your judgement. Do what is right for your scenario. +### Key Considerations -### Considerations +Before merging, review the following: -Make sure to consider the following things: +- **Is the right content being deleted?** Ensure no essential internal docs are being removed. +- **Is the correct content being moved?** Double-check that everything is in its proper place. +- **Are tests passing?** If not, what adjustments are needed to make the content mergeable? -* Are these PRs deleting the right content? Is any of the content in the docs dir used, for example, for internal docs that shouldn't be deleted? -* Is the right content being moved? -* Are tests passing? If not, what needs to be done to get the content into a mergable state? +Let us know if you encounter any blockers. Thanks for your help! From 279d79695fab9e5ae32c887dbee184ac8724bebd Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 25 Feb 2025 15:52:22 -0800 Subject: [PATCH 3/3] Update move-ref-docs.md --- docs/migration/guide/move-ref-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration/guide/move-ref-docs.md b/docs/migration/guide/move-ref-docs.md index 5bbc3e03e..4cd947783 100644 --- a/docs/migration/guide/move-ref-docs.md +++ b/docs/migration/guide/move-ref-docs.md @@ -184,7 +184,7 @@ Once everything is confirmed working, merge the pull request. Update [issue#130](https://github.com/elastic/docs-eng-team/issues/130) to reflect the completed migration. -## Managing Moved Reference Content +## How to manage moved reference content You've been assigned to a repository in [issue #130](https://github.com/elastic/docs-eng-team/issues/130). Now what?