You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
Check out the main branch.
Run git fetch origin then git pull to pull in the latest changes.
Run git -b <branch name> to create a new branch. For example, git -b issue-2175-8.5.0-rn.
Open the Security docs in your text editor (Atom or VS Code) and navigate to the release-notes folder.
Create a new asciidoc file in the release-notes folder. NOTE: Remember to include the asciidoc file extension when you name the file.
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).
Under the heading anchor, add the page title. It should be: == 8.5.
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
Return to your 8.5 release notes branch in the Security docs and open the 8.5 release notes file (8.5.asciidoc).
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[]
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.
Open the release-notes.asciidoc file.
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>>.
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[]
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:
Pull in the latest changes from the stack-docs repo's main branch.
Open the stack-docs repo in your text editor and navigate to the breaking.asciidoc file.
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]
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.
The text was updated successfully, but these errors were encountered:
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:
release_note:skip
labelAssumptions/Prereqs
It's assumed you've already completed the following:
security-docs
and thestack-docs
repossecurity-docs
repostack-docs
repoClone
security-docs
andstack-docs
reposFollow 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 thestack-docs
repo. Every release, we file a doc issue in thestack-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#2075Set up Security release notes in the Security docset
To prepare the Security release notes, do the following:
Set up the release notes file
Create a new release notes file for major and minor releases. To create the file, follow these steps:
main
branch.git fetch origin
thengit pull
to pull in the latest changes.git -b <branch name>
to create a new branch. For example,git -b issue-2175-8.5.0-rn
.release-notes
folder.release-notes
folder.NOTE: Remember to include the
asciidoc
file extension when you name the file.[[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
).== 8.5
.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
8.5.asciidoc
).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.
release-notes.asciidoc
file.* <<release-notes-8.5.0, {elastic-sec} version 8.5.0>>
.include::release-notes/8.5.asciidoc[]
Set up Security breaking changes in Stack docs
To prepare the Security breaking changes section in Stack docs release notes, do the following:
breaking.asciidoc
file.Prep the breaking changes section in the Stack docs
Follow these steps:
stack-docs
repo'smain
branch.stack-docs
repo in your text editor and navigate to thebreaking.asciidoc
file.{security-guide-all}/8.5/release-notes-header-8.5.0.html#breaking-changes-8.5.0[{elastic-sec} breaking changes]
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]
breaking.asciidoc
file after [DOCS] Add Elastic Security breaking changes to Installation and Upgrade Guide for 8.1 stack-docs#2076NOTE: 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
and8.5
branches.Troubleshooting
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:
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:release_note:skip
label and replace it with the appropriate release notes label (e.g.,release_note: feature
,release_note: fix
etc.)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.The text was updated successfully, but these errors were encountered: