Issue template form — alternate take #4308
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,105 @@ | ||||||||||||||||||||||||||||
| 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 | ||||||||||||||||||||||||||||
|
There was a problem hiding this comment. Would be a good place to ask whether there's an API doc impact? I'm also still unsure whether we should put a checkbox here, or add another text field. I'm leaning towards a text field so devs have the opportunity to add more detail, if they have more to share. @natasha-moore-elastic what are your thoughts here?
Suggested change
There was a problem hiding this comment. I agree, a text field is more flexible for additional info. Minor edit to suggestion above: There was a problem hiding this comment. Actually, once I committed the suggestion and looked at the preview, it seems like maybe this should go lower in the order of fields, maybe between "Feature differences" and "Prerequisites...." IMO it kind of sticks out toward the top. It's a required field so the submitter can't overlook it even if it's lower. There was a problem hiding this comment. Moved in 5dc55c8 to see how it looks in the preview; we can revert or relocate elsewhere if needed. There was a problem hiding this comment. Agree with having a text field rather than a checkbox so that more info can be provided. I can't seem to add a suggestion for line 24. I'd maybe update the description to something slightly more specific, like: There was a problem hiding this comment. I think you can't comment on the suggestion above because I already committed it, then moved it to a different part of the file. The description for API docs is now line 82; you should be able to comment on that in the diff tab, @natasha-moore-elastic. |
||||||||||||||||||||||||||||
| - 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: api-docs | ||||||||||||||||||||||||||||
| attributes: | ||||||||||||||||||||||||||||
| label: API docs impact | ||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||
| 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! | ||||||||||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the DE team is the only one that needs the extra/custom labels so they can track doc issues on their project board. One option for reducing the increasingly large label load is to agree on a set of labels that we can both use for tracking purposes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm actually thinking maybe we just omit the sentence about labels. That was originally copied from the Obs docs team's form, where they're using automation to auto-label issues based on responses throughout the form (and maybe manually adding labels interferes with that?).
We're not planning to implement that, at least not for our first iteration, so we'll end up manually adding and adjusting labels regardless. I don't see why we should discourage anyone if they want to try to help us label an issue. @jmikell821 WDYT?