Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] 8.5.0 Release Notes #2429

Closed
4 tasks
nastasha-solomon opened this issue Aug 31, 2022 · 3 comments · Fixed by #2519
Closed
4 tasks

[DOCS] 8.5.0 Release Notes #2429

nastasha-solomon opened this issue Aug 31, 2022 · 3 comments · Fixed by #2519

Comments

@nastasha-solomon
Copy link
Contributor

nastasha-solomon commented Aug 31, 2022

Description

This issue tracks release notes for the 8.5.0 release, which is GAing on October 18, 2022. The following sections explain how to:

  • Set up Security release notes in the Security docset
  • Set up Security breaking changes in the Stack docs
  • Manage release notes for Endpoint and ResponseOps features
  • Handle PRs that might be mistakenly labeled with the release_note:skip label

Assumptions/Prereqs

It's assumed you've already completed the following:

  • Cloned the security-docs and the stack-docs repos
  • Filed a release notes (RN) issue in the security-docs repo
  • Filed a breaking changes issue in the stack-docs repo

Clone security-docs and stack-docs repos

Follow these steps.

File breaking changes issue

The Elastic Installation and Upgrade Guide has a Breaking Changes section that describes each of the solution's breaking changes in a particular release. You can edit the section by modifying the breaking.asciidoc file, which is located within the stack-docs repo. Every release, we file a doc issue in the stack-docs repo to track our updates to the Security section of the file. When creating the doc issue, you can model it after: elastic/stack-docs#2075

Set up Security release notes in the Security docset

To prepare the Security release notes, do the following:

  • Create a new asciidoc file for the release notes.
  • Prep the breaking changes section.
  • Update the release notes index file.

Set up the release notes file

Create a new release notes file for major and minor releases. To create the file, follow these steps:

  1. Check out the main branch.
  2. Run git fetch origin then git pull to pull in the latest changes.
  3. Run git -b <branch name> to create a new branch. For example, git -b issue-2175-8.5.0-rn.
  4. Open the Security docs in your text editor (Atom or VS Code) and navigate to the release-notes folder.
  5. Create a new asciidoc file in the release-notes folder.
    NOTE: Remember to include the asciidoc file extension when you name the file.
  6. Add a heading anchor to the top of the file. It should be [[release-notes-header-8.5.0]]. You'll be referencing this anchor later when you insert a cross reference to the 8.5.0 release notes into the release notes index file (release-notes.asciidoc).
  7. Under the heading anchor, add the page title. It should be: == 8.5.
  8. Save the changes and open a PR.
    NOTE: Remember to add the release notes PR to the docs release issue in the dev repo. In the repo, go to the Issues tab to find the doc issue.

Prep the breaking changes section

  1. Return to your 8.5 release notes branch in the Security docs and open the 8.5 release notes file (8.5.asciidoc).
  2. Insert the Breaking Changes section above the Features section. Here's what the section should look like (you can copy and paste it):
[discrete]
[[breaking-changes-8.5.0]]
==== Breaking changes
// tag::breaking-changes[]
// NOTE: The breaking-changes tagged regions are re-used in the Elastic Installation and Upgrade Guide. The pull attribute is defined within this snippet so it properly resolves in the output.
:pull: https://github.com/elastic/kibana/pull/
**TBD**
// end::breaking-changes[]
  1. Save the changes and push them to your release notes PR.

Update the release notes index file

Insert a cross reference to the appropriate release notes file and add the release notes to the main TOC.

  1. Open the release-notes.asciidoc file.
  2. Under the section that summarizes the changes in each release, add a cross reference to the 8.5.0 release notes. It should be: * <<release-notes-8.5.0, {elastic-sec} version 8.5.0>>.
  3. Go the end of the file and add an include for the the 8.5.0 release notes. It should be: include::release-notes/8.5.asciidoc[]
  4. Save the changes and push them to your release notes PR.

Set up Security breaking changes in Stack docs

To prepare the Security breaking changes section in Stack docs release notes, do the following:

  • Prep the breaking changes section for Security within the breaking.asciidoc file.

Prep the breaking changes section in the Stack docs

Follow these steps:

  1. Pull in the latest changes from the stack-docs repo's main branch.
  2. Open the stack-docs repo in your text editor and navigate to the breaking.asciidoc file.
  3. Go to the "Elastic Security breaking changes" section and make the following changes:
    • Update the release version number that's included in the URL that references the latest Security release notes. For this release, the referenced URL should be: {security-guide-all}/8.5/release-notes-header-8.5.0.html#breaking-changes-8.5.0[{elastic-sec} breaking changes]
    • Update the include statement so it references the 8.5 release notes asciidoc file. For this release, ensure the include statement is: include::{security-repo-dir}/release-notes/8.5.asciidoc[tag=breaking-changes]
  4. Save your changes and open a PR. You can model the issue and PR for updating the Stack doc's breaking.asciidoc file after [DOCS] Add Elastic Security breaking changes to Installation and Upgrade Guide for 8.1 stack-docs#2076
    NOTE: The CI checks for your Stack docs PR will fail until you've merged your PR for the 8.5 Security release notes into the main and 8.5 branches.

Troubleshooting

  • Refer to the Asciidoc spec for including content of tagged regions for more on how includes and tagged snippets work.
  • Links inside tagged content must be full URL links, not relative links or an internal anchor references. Using attributes to represent part of the URL is OK. Basically, treat links as if they're external or cross-document links.
  • The stack docs PR might take an hour (or longer) to complete. This usually happens if something triggers the CI checks to rebuild the full Elastic docset. In these situations, the best course of action is to wait it out.

Managing RNs for Endpoint features

Ping Daniel Furullo to get a list of Endpoint features, bug fixes, and known issues that need to release-noted for the release. It might be helpful to create a doc issue similar to this one to track the information.

IMPORTANT: When you add the PR to the Endpoint feature/bug/known issue, use the hardcoded URL to create the reference link, for example.

Background

Some background on why we handle Endpoint PRs this way...

The Endpoint team is part of the Security solution team but they track their issues and PRs in separate repos:

  • elastic/endpoint: This is a public repo that’s open to the public. If the Endpoint team wants to share more information about the bug, they’ll usually file an issue in this repo and share the issue number with us.
  • elastic/endpoint-dev: This is a private repo that the Endpoint team uses to track issues and PRs. Chances are that we’ll never be asked to link to an issue or PR in this repo because users won’t be able to access it.

Because the Endpoint team doesn’t store their PRs in the Kibana repo, our release notes tool can’t find them.

Managing RNs for ResponseOps features

ResponseOps features for cases, connectors, and alerts are always doc'd in the Kibana release notes unless they are Security-specific features. In these situations, the feature will likely be double-doc'd, once in the Kibana release notes and another in the Security release notes. If the actual code changes require separate PRs, the feature will have different PRs in each set of release notes.

Investigating PRs that are labeled to be "skipped"

Sometimes the release_note:skip label is mistakenly added to a PR that actually needs release notes. If you encounter a PR like this, ping the PR owner or team lead on Slack and ask them whether the PR needs release notes. If it does, ask the PR owner to do the following:

  • Remove the release_note:skip label and replace it with the appropriate release notes label (e.g., release_note: feature, release_note: fix etc.)
  • Provide a short, descriptive summary of the PR. Summaries can be added as a comment in the PR or included in the PR's description. Refer to past versions of the Security release notes for summary models.
    NOTE: The PR title is the best place to put a release notes summary for a bug fix. This is because our release notes tool retrieves the PR title when forming a PR's release notes.

Handling known issues

At the moment, we do not have a label to flag bugs as “known issues”. There was some conversation about creating one to make it easier for docs to track known issues in releases, but that conversation hasn’t been resolved yet.

Currently, we rely on members of the engineering team (e.g., dev, a PM, or a team lead) to notify us when a PR needs to be release-noted as a known issue. There are a variety of ways they can communicate with us, but we encourage them to post the request directly in our #security-docs slack channel. Another option is to file a doc issue in our security-docs repo.

@nastasha-solomon nastasha-solomon self-assigned this Aug 31, 2022
@nastasha-solomon nastasha-solomon changed the title [DOCS] [DRAFT] 8.5.0 Release Notes [DOCS] 8.5.0 Release Notes Sep 15, 2022
@nastasha-solomon
Copy link
Contributor Author

nastasha-solomon commented Sep 15, 2022

Reminder to myself that we'll need to release-note the PR for elastic/detection-rules#2260 once it's created/merged.
cc: @benironside @w0rk3r @luigidellaquila

@nastasha-solomon
Copy link
Contributor Author

Breaking changes for the risk score features are doc'd at https://github.com/elastic/security-team/issues/4898.

@nastasha-solomon
Copy link
Contributor Author

Confirmed with @w0rk3r that elastic/detection-rules#2260 was fixed in elastic/elasticsearch#90064 so I’ll be doc'ing the PR in as a fixed bug in 8.5.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants