From 1504d6c6ec8f7a85f5278559acca54f57704356d Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 21 Nov 2023 15:27:06 -0500 Subject: [PATCH 1/6] Add labels to bug issue template --- .github/ISSUE_TEMPLATE/bug-report.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 83da5add08..65e7cee833 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -2,7 +2,7 @@ name: Bug report about: Report documentation bugs or fixes. title: "[BUG]" -labels: bug +labels: bug, known-issue, release-notes assignees: '' --- From 6a152b6437745c62723140ab17957f12413b8e88 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 21 Nov 2023 15:29:20 -0500 Subject: [PATCH 2/6] Rename template file, replace with form YAML --- .github/ISSUE_TEMPLATE/documentation-issue.md | 24 ----- .../ISSUE_TEMPLATE/internal-docs-request.yaml | 94 +++++++++++++++++++ 2 files changed, 94 insertions(+), 24 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/documentation-issue.md create mode 100644 .github/ISSUE_TEMPLATE/internal-docs-request.yaml diff --git a/.github/ISSUE_TEMPLATE/documentation-issue.md b/.github/ISSUE_TEMPLATE/documentation-issue.md deleted file mode 100644 index 99f4c9e11c..0000000000 --- a/.github/ISSUE_TEMPLATE/documentation-issue.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: Documentation Issue -about: Describe your Elastic security documentation issue. -title: '' -labels: '' -assignees: '' - ---- - -## Description - -[insert a summary of the doc issue here. Background information is especially useful]. Include a link to the related issue or pull request. - -## Acceptance Test Criteria - -List all the ATC of each action and its intended result. -For example: As a user, when [action (e.g., viewing, clicking, selecting, etc.)] I should [insert the expected result]. - - -## Notes - -- Add all appropriate labels to the issue, especially the version number label. -- Be sure to add any necessary screenshots, code text or console commands for clarity. -- Include any conditions or caveats that may affect customers. diff --git a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml new file mode 100644 index 0000000000..78441b5401 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml @@ -0,0 +1,94 @@ +name: "Internal documentation request (Elastic employees)" +description: Request a documentation change or enhancement. +title: "[Request] " +body: + - type: markdown + attributes: + value: | + Hello! This form will create an issue that the Security docs team will triage and prioritize. Please do not add any labels to your issue — we'll take care of that. + - type: textarea + id: description + attributes: + label: Description + description: Describe what needs to be documented. What details do users need to know about? What are typical workflows for the feature? + placeholder: | + What: We're introducing new feature A. + Why: This feature will make X, Y, and Z easier for the user. + How: The user navigates to *Foo* → *Bar*, then clicks the *Wow* button. + validations: + required: true + - type: textarea + id: related + attributes: + label: Background & resources + description: | + Please include relevant pull requests or issues, and at least one point of contact. + Also include any test environments where we can access the feature, and list steps to generate data we can test. + value: | + * PRs: + * Issues/metas: + * Point of contact: + * Test environments: + validations: + required: true + - type: dropdown + id: doc-set + attributes: + label: Which documentation set does this change impact? + description: ESS (classic), serverless, or both? + options: + - ESS and serverless + - ESS only + - Serverless only + - Unknown + default: 0 + validations: + required: true + - type: dropdown + id: version-ess + attributes: + label: ESS release + description: Select a release version if your request is tied to the Elastic Stack release schedule. + options: + - '8.12' + - '8.13' + - '8.14' + - '8.15' + - '8.16' + - 'N/A' + default: 0 + validations: + required: true + - type: input + id: release-serverless + attributes: + label: Serverless release + description: When do you expect the feature to be promoted and available in the _**serverless production environment**_? + placeholder: The week of April 1, 2024 + validations: + required: true + - type: textarea + id: doc-set-differences + attributes: + label: Feature differences + description: If you selected both ESS and serverless above, please describe how, if at all, the feature differs in each platform. + placeholder: The feature is identical in ESS and serverless. + validations: + required: true + - type: textarea + id: prereqs + attributes: + label: Prerequisites, privileges, feature flags + description: | + What are the feature's requirements _**in both ESS and serverless**_? What subscription tiers or user role privileges are required? + Is the feature behind a feature flag, and if so, what is it? + placeholder: | + * ESS: Requires Enterprise subscription; `write` privilege for `yada-yada-*` index + * Serverless: Requires Security Analytics Complete tier and Endpoint Protection Complete add-on; X, Y, or Z user roles + * Feature flag: None + validations: + required: false + - type: markdown + attributes: + value: | + Thanks for completing this form to help us understand and plan accordingly. We'll be in touch soon! From 810de836ff18c26d748ad8322d88581161148096 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 28 Nov 2023 15:10:56 -0500 Subject: [PATCH 3/6] Add API docs text field Co-authored-by: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/internal-docs-request.yaml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml index 78441b5401..cfe3cbc752 100644 --- a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml +++ b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml @@ -17,6 +17,17 @@ body: How: The user navigates to *Foo* → *Bar*, then clicks the *Wow* button. validations: required: true + - type: textarea + id: description + attributes: + label: API docs impact + description: Describe what needs to be documented and provide example responses. What parameters and endpoints need to be documented? + placeholder: | + What: We're introducing new endpoint A. + Why: Users can send a request to endpoint A to use feature A. + How: The user provides the specific information in the request + validations: + required: true - type: textarea id: related attributes: From 87527bffdb5fe3c1c05eb901af35a1d8f63cf0c6 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 28 Nov 2023 15:21:24 -0500 Subject: [PATCH 4/6] Fix error: unique id value --- .github/ISSUE_TEMPLATE/internal-docs-request.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml index cfe3cbc752..c4ecdd7ea2 100644 --- a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml +++ b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml @@ -18,7 +18,7 @@ body: validations: required: true - type: textarea - id: description + id: api-docs attributes: label: API docs impact description: Describe what needs to be documented and provide example responses. What parameters and endpoints need to be documented? From 5dc55c88ac51157206a3ff75ee016b1fea574566 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 28 Nov 2023 15:28:37 -0500 Subject: [PATCH 5/6] Relocate API docs section --- .../ISSUE_TEMPLATE/internal-docs-request.yaml | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml index c4ecdd7ea2..13c7d91694 100644 --- a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml +++ b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml @@ -17,17 +17,6 @@ body: How: The user navigates to *Foo* → *Bar*, then clicks the *Wow* button. validations: required: true - - type: textarea - id: api-docs - attributes: - label: API docs impact - description: Describe what needs to be documented and provide example responses. What parameters and endpoints need to be documented? - placeholder: | - What: We're introducing new endpoint A. - Why: Users can send a request to endpoint A to use feature A. - How: The user provides the specific information in the request - validations: - required: true - type: textarea id: related attributes: @@ -86,6 +75,17 @@ body: placeholder: The feature is identical in ESS and serverless. validations: required: true + - type: textarea + id: api-docs + attributes: + label: API docs impact + description: Describe what needs to be documented and provide example responses. What parameters and endpoints need to be documented? + placeholder: | + What: We're introducing new endpoint A. + Why: Users can send a request to endpoint A to use feature A. + How: The user provides the specific information in the request + validations: + required: true - type: textarea id: prereqs attributes: From 4298939f1745ddcd3069215b5db3ddef6805f9e1 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 29 Nov 2023 14:32:23 -0500 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/internal-docs-request.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml index 13c7d91694..19aa608881 100644 --- a/.github/ISSUE_TEMPLATE/internal-docs-request.yaml +++ b/.github/ISSUE_TEMPLATE/internal-docs-request.yaml @@ -79,11 +79,11 @@ body: id: api-docs attributes: label: API docs impact - description: Describe what needs to be documented and provide example responses. What parameters and endpoints need to be documented? + description: Please provide endpoint and parameter descriptions, and request and response examples. placeholder: | What: We're introducing new endpoint A. Why: Users can send a request to endpoint A to use feature A. - How: The user provides the specific information in the request + How: The user provides the specific information in the request. validations: required: true - type: textarea