From c8887688408486ea7a635af3455fddcd3fb44763 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 12:58:31 +0100 Subject: [PATCH 01/15] feat: Update issue templates & process docs This commit updates the issue templates into the repository, converting them from plain Markdown templates to interactive forms. It also updates the process documentation, re-organising them into topic groups and adding guidance on the level of desired detail for requests. --- .github/ISSUE_TEMPLATE/1-general_request.md | 36 +++++++++++++++ .github/ISSUE_TEMPLATE/1-general_request.yml | 44 +++++++++++++++++++ ...eature_request.md => 2-feature_request.md} | 0 .../{2-bug_report.md => 3-bug_report.md} | 0 .../{3-story_task.md => 4-story_task.md} | 0 ...{4-epic_overview.md => 5-epic_overview.md} | 0 .../{5-content_plan.md => 6-content_plan.md} | 0 CONTRIBUTING.md | 11 +++-- documentation/README.md | 2 +- .../{writing-hugo.md => hugo-content.md} | 0 documentation/include-files.md | 2 +- 11 files changed, 87 insertions(+), 8 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/1-general_request.md create mode 100644 .github/ISSUE_TEMPLATE/1-general_request.yml rename .github/ISSUE_TEMPLATE/{1-feature_request.md => 2-feature_request.md} (100%) rename .github/ISSUE_TEMPLATE/{2-bug_report.md => 3-bug_report.md} (100%) rename .github/ISSUE_TEMPLATE/{3-story_task.md => 4-story_task.md} (100%) rename .github/ISSUE_TEMPLATE/{4-epic_overview.md => 5-epic_overview.md} (100%) rename .github/ISSUE_TEMPLATE/{5-content_plan.md => 6-content_plan.md} (100%) rename documentation/{writing-hugo.md => hugo-content.md} (100%) diff --git a/.github/ISSUE_TEMPLATE/1-general_request.md b/.github/ISSUE_TEMPLATE/1-general_request.md new file mode 100644 index 000000000..d446df07a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-general_request.md @@ -0,0 +1,36 @@ +--- +name: General request +about: This template is for recording general documentation requests +title: "" +labels: "enhancement" +projects: ["nginx/22"] +assignees: "" +--- + +https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms + +*Remove italicized directions as relevant to reduce noise in the issue description.* + +### What would you like the documentation team to work on? + +*Please describe your request with as much detail as possible.* + +### Who is the person directly responsible for initiating this request? + +*Name the specific stakeholders for this request.* + +### Is this request part of a larger initiative or project? + +*Mention the project related to the broader impact this request relates to.* + +### Is there important information necessary to contextualise this request? + +*If the request is particularly large, you may want to organise a meeting before filing an issue.* + +### Does this request have a due date? + +*You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it.* + +### Any additional information + +*Add any remaining detail for this request not covered by the above questions.* \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/1-general_request.yml b/.github/ISSUE_TEMPLATE/1-general_request.yml new file mode 100644 index 000000000..591054207 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-general_request.yml @@ -0,0 +1,44 @@ +name: General request +description: Make a general documentation request. +title: "[Request]: " +body: + - type: textarea + id: what-work + label: What would you like the documentation team to work on? + description: Please describe your request with as much detail as possible. + - type: dropdown + id: what-product + label: Which product or products does this relate to? + description: You can figure this out based on page URL + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + - type: textarea + id: direct-responsibility + label: Who is the person directly responsible for initiating this request? + description: Name the specific person that made this request. + - type: textarea + id: request-scope + label: Is this request part of a larger initiative or project? + description: If it is, name the project the request relates to + - type: textarea + id: request-constraints + label: Are there important constraints for this request? + description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request + - type: textarea + id: request-deadline + label: Does this request have a due date? + description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. + - type: textarea + id: additional-information + label: Any additional information + description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/1-feature_request.md b/.github/ISSUE_TEMPLATE/2-feature_request.md similarity index 100% rename from .github/ISSUE_TEMPLATE/1-feature_request.md rename to .github/ISSUE_TEMPLATE/2-feature_request.md diff --git a/.github/ISSUE_TEMPLATE/2-bug_report.md b/.github/ISSUE_TEMPLATE/3-bug_report.md similarity index 100% rename from .github/ISSUE_TEMPLATE/2-bug_report.md rename to .github/ISSUE_TEMPLATE/3-bug_report.md diff --git a/.github/ISSUE_TEMPLATE/3-story_task.md b/.github/ISSUE_TEMPLATE/4-story_task.md similarity index 100% rename from .github/ISSUE_TEMPLATE/3-story_task.md rename to .github/ISSUE_TEMPLATE/4-story_task.md diff --git a/.github/ISSUE_TEMPLATE/4-epic_overview.md b/.github/ISSUE_TEMPLATE/5-epic_overview.md similarity index 100% rename from .github/ISSUE_TEMPLATE/4-epic_overview.md rename to .github/ISSUE_TEMPLATE/5-epic_overview.md diff --git a/.github/ISSUE_TEMPLATE/5-content_plan.md b/.github/ISSUE_TEMPLATE/6-content_plan.md similarity index 100% rename from .github/ISSUE_TEMPLATE/5-content_plan.md rename to .github/ISSUE_TEMPLATE/6-content_plan.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3988f3345..3141d7b41 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,14 +34,14 @@ If you'd like to discuss something NGINX-related that doesn't involve documentat ## Submit a pull request -Before making documentation changes, you should view the [documentation style guide](/documentation/style-guide.md) and [Managing content with Hugo](/documentation/writing-hugo.md). +Before making documentation changes, you should view the [documentation style guide](/documentation/style-guide.md) and [Managing content with Hugo](/documentation/hugo-content.md). To understand how we use Git in this repository, read our [Git conventions](/documentation/git-conventions.md) documentation. The broad workflow is as follows: - Fork the NGINX repository - - If you're an F5/NGINX user, you can work from a clone + - If you're an F5/NGINX user, you can branch directly with a clone - Create a branch - Implement your changes in your branch - Submit a pull request (PR) when your changes are ready for review @@ -53,10 +53,9 @@ Alternatively, you're welcome to suggest improvements to highlight problems with To ensure a balance between work carried out by the NGINX team while encouraging community involvement on this project, we use the following issue lifecycle: -- A new issue is created by a community member -- An owner on the NGINX team is assigned to the issue; this owner shepherds the issue through the subsequent stages in the issue lifecycle -- The owner assigns one or more [labels](https://github.com/nginxinc/oss-docs/issues/labels) to the issue -- The owner, in collaboration with the community member, determines what milestone to attach to an issue. They may be milestones correspond to product releases +- A new issue is created by +- A maintainer from the F5 team is assigned to the issue; this maintainer shepherds the issue through the subsequent stages in the issue lifecycle +- The maintainer assigns one or more [labels](https://github.com/nginx/documentation/labels) to the issue ## Additional NGINX documentation diff --git a/documentation/README.md b/documentation/README.md index 169a891f5..b23b53fed 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -16,7 +16,7 @@ If you're interested in contributing to the [NGINX documentation website](https: - [Git conventions](/documentation/git-conventions.md) - [Information architecture heuristics](/documentation/ia-heuristics.md) - [Maintainers etiquette](/documentation/maintainers-etiquette.md) -- [Managing content with Hugo](/documentation/writing-hugo.md) +- [Managing content with Hugo](/documentation/hugo-content.md) - [Proposals](/documentation/proposals/README.md) - [Set up pre-commit](/documentation/pre-commit.md) - [Using include files](/documentation/include-files.md) diff --git a/documentation/writing-hugo.md b/documentation/hugo-content.md similarity index 100% rename from documentation/writing-hugo.md rename to documentation/hugo-content.md diff --git a/documentation/include-files.md b/documentation/include-files.md index 096ba4661..dcec616c4 100644 --- a/documentation/include-files.md +++ b/documentation/include-files.md @@ -16,7 +16,7 @@ The files are located in the [content/includes](https://github.com/nginxinc/docs Putting the previous example in any Markdown file would embed the contents of `content/includes/use-cases/docker-registry-instructions.md` wherever the shortcode was used. -For guidance on other Hugo shortcodes, read the [Managing content with Hugo](/documentation/writing-hugo.md) document. +For guidance on other Hugo shortcodes, read the [Managing content with Hugo](/documentation/hugo-content.md) document. ## Guidelines for include files From 76e23f5e4dbb81d82f61e0c4d99b940ef1e6acc2 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:05:05 +0100 Subject: [PATCH 02/15] fix: Incorrect attribute nesting --- .github/ISSUE_TEMPLATE/1-general_request.md | 36 ----------- .github/ISSUE_TEMPLATE/1-general_request.yml | 66 +++++++++++++------- 2 files changed, 42 insertions(+), 60 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/1-general_request.md diff --git a/.github/ISSUE_TEMPLATE/1-general_request.md b/.github/ISSUE_TEMPLATE/1-general_request.md deleted file mode 100644 index d446df07a..000000000 --- a/.github/ISSUE_TEMPLATE/1-general_request.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -name: General request -about: This template is for recording general documentation requests -title: "" -labels: "enhancement" -projects: ["nginx/22"] -assignees: "" ---- - -https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms - -*Remove italicized directions as relevant to reduce noise in the issue description.* - -### What would you like the documentation team to work on? - -*Please describe your request with as much detail as possible.* - -### Who is the person directly responsible for initiating this request? - -*Name the specific stakeholders for this request.* - -### Is this request part of a larger initiative or project? - -*Mention the project related to the broader impact this request relates to.* - -### Is there important information necessary to contextualise this request? - -*If the request is particularly large, you may want to organise a meeting before filing an issue.* - -### Does this request have a due date? - -*You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it.* - -### Any additional information - -*Add any remaining detail for this request not covered by the above questions.* \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/1-general_request.yml b/.github/ISSUE_TEMPLATE/1-general_request.yml index 591054207..b80ee7609 100644 --- a/.github/ISSUE_TEMPLATE/1-general_request.yml +++ b/.github/ISSUE_TEMPLATE/1-general_request.yml @@ -4,40 +4,58 @@ title: "[Request]: " body: - type: textarea id: what-work - label: What would you like the documentation team to work on? - description: Please describe your request with as much detail as possible. + attributes: + label: What would you like the documentation team to work on? + description: Please describe your request with as much detail as possible. + validations: + required: true - type: dropdown id: what-product - label: Which product or products does this relate to? - description: You can figure this out based on page URL - multiple: true - options: - - F5 DoS for NGINX - - F5 WAF for NGINX - - NGINX Agent - - NGINXaaS for Azure - - NGINX Gateway Fabric - - NGINX Ingress Controller - - NGINX Instance Manager - - NGINX One Console - - NGINX Plus - - Other + attributes: + label: Which product or products does this relate to? + description: You can figure this out based on page URL + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true - type: textarea id: direct-responsibility - label: Who is the person directly responsible for initiating this request? - description: Name the specific person that made this request. + attributes: + label: Who is the person directly responsible for initiating this request? + description: Name the specific person that made this request. + validations: + required: true - type: textarea id: request-scope - label: Is this request part of a larger initiative or project? - description: If it is, name the project the request relates to + attributes: + label: Is this request part of a larger initiative or project? + description: If it is, name the project the request relates to + validations: + required: true - type: textarea id: request-constraints - label: Are there important constraints for this request? - description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request + attributes: + label: Are there important constraints for this request? + description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request + validations: + required: true - type: textarea id: request-deadline - label: Does this request have a due date? - description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. + attributes: + label: Does this request have a due date? + description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. + validations: + required: true - type: textarea id: additional-information label: Any additional information From 48610416b17a2846fcbff8751ca789f74e16a6c3 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:11:44 +0100 Subject: [PATCH 03/15] fix: test --- .github/ISSUE_TEMPLATE/1-general_request.yml | 101 +++++++++---------- 1 file changed, 50 insertions(+), 51 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-general_request.yml b/.github/ISSUE_TEMPLATE/1-general_request.yml index b80ee7609..bce6eb5f7 100644 --- a/.github/ISSUE_TEMPLATE/1-general_request.yml +++ b/.github/ISSUE_TEMPLATE/1-general_request.yml @@ -9,54 +9,53 @@ body: description: Please describe your request with as much detail as possible. validations: required: true - - type: dropdown - id: what-product - attributes: - label: Which product or products does this relate to? - description: You can figure this out based on page URL - multiple: true - options: - - F5 DoS for NGINX - - F5 WAF for NGINX - - NGINX Agent - - NGINXaaS for Azure - - NGINX Gateway Fabric - - NGINX Ingress Controller - - NGINX Instance Manager - - NGINX One Console - - NGINX Plus - - Other - validations: - required: true - - type: textarea - id: direct-responsibility - attributes: - label: Who is the person directly responsible for initiating this request? - description: Name the specific person that made this request. - validations: - required: true - - type: textarea - id: request-scope - attributes: - label: Is this request part of a larger initiative or project? - description: If it is, name the project the request relates to - validations: - required: true - - type: textarea - id: request-constraints - attributes: - label: Are there important constraints for this request? - description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request - validations: - required: true - - type: textarea - id: request-deadline - attributes: - label: Does this request have a due date? - description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. - validations: - required: true - - type: textarea - id: additional-information - label: Any additional information - description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file + # - type: dropdown + # id: what-product + # attributes: + # label: Which product or products does this relate to? + # multiple: true + # options: + # - F5 DoS for NGINX + # - F5 WAF for NGINX + # - NGINX Agent + # - NGINXaaS for Azure + # - NGINX Gateway Fabric + # - NGINX Ingress Controller + # - NGINX Instance Manager + # - NGINX One Console + # - NGINX Plus + # - Other + # validations: + # required: true + # - type: textarea + # id: direct-responsibility + # attributes: + # label: Who is the person directly responsible for initiating this request? + # description: Name the specific person that made this request. + # validations: + # required: true + # - type: textarea + # id: request-scope + # attributes: + # label: Is this request part of a larger initiative or project? + # description: If it is, name the project the request relates to + # validations: + # required: true + # - type: textarea + # id: request-constraints + # attributes: + # label: Are there important constraints for this request? + # description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request + # validations: + # required: true + # - type: textarea + # id: request-deadline + # attributes: + # label: Does this request have a due date? + # description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. + # validations: + # required: true + # - type: textarea + # id: additional-information + # label: Any additional information + # description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file From dfc00946ccc7b2b4ffda5771008135d175fbc67f Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:20:15 +0100 Subject: [PATCH 04/15] feat: Unhide other sections --- .github/ISSUE_TEMPLATE/1-general_request.yml | 100 +++++++++---------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-general_request.yml b/.github/ISSUE_TEMPLATE/1-general_request.yml index bce6eb5f7..6506ad0fc 100644 --- a/.github/ISSUE_TEMPLATE/1-general_request.yml +++ b/.github/ISSUE_TEMPLATE/1-general_request.yml @@ -9,53 +9,53 @@ body: description: Please describe your request with as much detail as possible. validations: required: true - # - type: dropdown - # id: what-product - # attributes: - # label: Which product or products does this relate to? - # multiple: true - # options: - # - F5 DoS for NGINX - # - F5 WAF for NGINX - # - NGINX Agent - # - NGINXaaS for Azure - # - NGINX Gateway Fabric - # - NGINX Ingress Controller - # - NGINX Instance Manager - # - NGINX One Console - # - NGINX Plus - # - Other - # validations: - # required: true - # - type: textarea - # id: direct-responsibility - # attributes: - # label: Who is the person directly responsible for initiating this request? - # description: Name the specific person that made this request. - # validations: - # required: true - # - type: textarea - # id: request-scope - # attributes: - # label: Is this request part of a larger initiative or project? - # description: If it is, name the project the request relates to - # validations: - # required: true - # - type: textarea - # id: request-constraints - # attributes: - # label: Are there important constraints for this request? - # description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request - # validations: - # required: true - # - type: textarea - # id: request-deadline - # attributes: - # label: Does this request have a due date? - # description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. - # validations: - # required: true - # - type: textarea - # id: additional-information - # label: Any additional information - # description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file + - type: dropdown + id: what-product + attributes: + label: Which product or products does this relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + id: direct-responsibility + attributes: + label: Who is the person directly responsible for initiating this request? + description: Name the specific person that made this request. + validations: + required: true + - type: textarea + id: request-scope + attributes: + label: Is this request part of a larger initiative or project? + description: If it is, name the project the request relates to + validations: + required: true + - type: textarea + id: request-constraints + attributes: + label: Are there important constraints for this request? + description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request + validations: + required: true + - type: textarea + id: request-deadline + attributes: + label: Does this request have a due date? + description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. + validations: + required: true + - type: textarea + id: additional-information + label: Any additional information + description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file From 50dbb09532cc91881bedad2f22bd5e735d693d8d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:26:59 +0100 Subject: [PATCH 05/15] fix: Remove unnecessary IDs, nest last item --- .github/ISSUE_TEMPLATE/1-general_request.yml | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-general_request.yml b/.github/ISSUE_TEMPLATE/1-general_request.yml index 6506ad0fc..a23cbeb5f 100644 --- a/.github/ISSUE_TEMPLATE/1-general_request.yml +++ b/.github/ISSUE_TEMPLATE/1-general_request.yml @@ -3,16 +3,14 @@ description: Make a general documentation request. title: "[Request]: " body: - type: textarea - id: what-work attributes: label: What would you like the documentation team to work on? description: Please describe your request with as much detail as possible. validations: required: true - type: dropdown - id: what-product attributes: - label: Which product or products does this relate to? + label: Which product or products does this request relate to? multiple: true options: - F5 DoS for NGINX @@ -28,34 +26,30 @@ body: validations: required: true - type: textarea - id: direct-responsibility attributes: label: Who is the person directly responsible for initiating this request? description: Name the specific person that made this request. validations: required: true - type: textarea - id: request-scope attributes: label: Is this request part of a larger initiative or project? description: If it is, name the project the request relates to validations: required: true - type: textarea - id: request-constraints attributes: label: Are there important constraints for this request? description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request validations: required: true - type: textarea - id: request-deadline attributes: label: Does this request have a due date? description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. validations: required: true - type: textarea - id: additional-information - label: Any additional information - description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file + attributes: + label: Any additional information + description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file From 34a70d8a9b320cc745d7458cee54689a6ff9d619 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:52:13 +0100 Subject: [PATCH 06/15] feat: Rename existing templates, update first --- .github/ISSUE_TEMPLATE/1-idea_suggestion.yml | 52 +++++++++++++++++++ .../{3-bug_report.md => 2-bug_report.yml} | 0 .github/ISSUE_TEMPLATE/2-feature_request.md | 23 -------- ...eral_request.yml => 3-general_request.yml} | 6 +-- .../{4-story_task.md => 4-story_task.yml} | 0 .../{6-content_plan.md => 5-content_plan.yml} | 0 ...5-epic_overview.md => 6-epic_overview.yml} | 0 7 files changed, 55 insertions(+), 26 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/1-idea_suggestion.yml rename .github/ISSUE_TEMPLATE/{3-bug_report.md => 2-bug_report.yml} (100%) delete mode 100644 .github/ISSUE_TEMPLATE/2-feature_request.md rename .github/ISSUE_TEMPLATE/{1-general_request.yml => 3-general_request.yml} (88%) rename .github/ISSUE_TEMPLATE/{4-story_task.md => 4-story_task.yml} (100%) rename .github/ISSUE_TEMPLATE/{6-content_plan.md => 5-content_plan.yml} (100%) rename .github/ISSUE_TEMPLATE/{5-epic_overview.md => 6-epic_overview.yml} (100%) diff --git a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml new file mode 100644 index 000000000..e82fbb61c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml @@ -0,0 +1,52 @@ +name: Documentation idea +description: Suggest an idea for improving documentation +title: "[Idea]: " +body: + - type: textarea + attributes: + label: What is your idea for improving documentation? + description: Describe your idea with as much information as possible. + validations: + required: true + - type: dropdown + attributes: + label: Which product or products does this request relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + attributes: + label: Is this idea related to a larger problem? + description: If you have identified specific issues, it might be part of a design pattern. + validations: + required: true + - type: textarea + attributes: + label: What alternative ways have you thought of to implement you idea? + description: There are often multiple ways to do one thing: context is important. + validations: + required: true + - type: textarea + attributes: + label: Any additional information + description: Add any remaining detail for this request not covered by the above questions. + + +### Describe alternatives you've considered + +A clear and concise description of any alternative solutions or features you've considered. + +### Additional context + +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/3-bug_report.md b/.github/ISSUE_TEMPLATE/2-bug_report.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/3-bug_report.md rename to .github/ISSUE_TEMPLATE/2-bug_report.yml diff --git a/.github/ISSUE_TEMPLATE/2-feature_request.md b/.github/ISSUE_TEMPLATE/2-feature_request.md deleted file mode 100644 index 8b2820beb..000000000 --- a/.github/ISSUE_TEMPLATE/2-feature_request.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: "" -labels: "enhancement" -assignees: "" ---- - -### Is your feature request related to a problem? Please describe - -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -### Describe the solution you'd like - -A clear and concise description of what you want to happen. - -### Describe alternatives you've considered - -A clear and concise description of any alternative solutions or features you've considered. - -### Additional context - -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/1-general_request.yml b/.github/ISSUE_TEMPLATE/3-general_request.yml similarity index 88% rename from .github/ISSUE_TEMPLATE/1-general_request.yml rename to .github/ISSUE_TEMPLATE/3-general_request.yml index a23cbeb5f..e99203299 100644 --- a/.github/ISSUE_TEMPLATE/1-general_request.yml +++ b/.github/ISSUE_TEMPLATE/3-general_request.yml @@ -34,19 +34,19 @@ body: - type: textarea attributes: label: Is this request part of a larger initiative or project? - description: If it is, name the project the request relates to + description: If it is, name the project the request relates to. validations: required: true - type: textarea attributes: label: Are there important constraints for this request? - description: If the constraints are particularly complex, you may wish to organise a meeting instead of filing a request + description: If the constraints are particularly complex, you may wish to organise a meeting before filing a request. validations: required: true - type: textarea attributes: label: Does this request have a due date? - description: You should name any specific date you have in mind for this request, or any dependencies/blockers that would determine it. + description: You should name any specific date or milestones (Such as "Q3") you have in mind for this request, and any dependencies or blockers affecting it. validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/4-story_task.md b/.github/ISSUE_TEMPLATE/4-story_task.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/4-story_task.md rename to .github/ISSUE_TEMPLATE/4-story_task.yml diff --git a/.github/ISSUE_TEMPLATE/6-content_plan.md b/.github/ISSUE_TEMPLATE/5-content_plan.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/6-content_plan.md rename to .github/ISSUE_TEMPLATE/5-content_plan.yml diff --git a/.github/ISSUE_TEMPLATE/5-epic_overview.md b/.github/ISSUE_TEMPLATE/6-epic_overview.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/5-epic_overview.md rename to .github/ISSUE_TEMPLATE/6-epic_overview.yml From 88a67c5ecec50c19af94be0b796b598dc000d641 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:53:24 +0100 Subject: [PATCH 07/15] fix: Syntax error caused by colon --- .github/ISSUE_TEMPLATE/1-idea_suggestion.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml index e82fbb61c..65cb52d00 100644 --- a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml +++ b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml @@ -34,7 +34,7 @@ body: - type: textarea attributes: label: What alternative ways have you thought of to implement you idea? - description: There are often multiple ways to do one thing: context is important. + description: There are often multiple ways to do one thing - context is important. validations: required: true - type: textarea From 30c3b1026223d9f474af9a2772b891f2b80c543b Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:54:05 +0100 Subject: [PATCH 08/15] fix: Remove unnecessary lines --- .github/ISSUE_TEMPLATE/1-idea_suggestion.yml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml index 65cb52d00..94dd5b751 100644 --- a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml +++ b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml @@ -41,12 +41,3 @@ body: attributes: label: Any additional information description: Add any remaining detail for this request not covered by the above questions. - - -### Describe alternatives you've considered - -A clear and concise description of any alternative solutions or features you've considered. - -### Additional context - -Add any other context or screenshots about the feature request here. From f36097eb6bd53a62eff90a6e512a587ec9b73b5d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 13:54:54 +0100 Subject: [PATCH 09/15] fix: Needless nesting --- .github/ISSUE_TEMPLATE/1-idea_suggestion.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml index 94dd5b751..0b72f255b 100644 --- a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml +++ b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml @@ -35,8 +35,8 @@ body: attributes: label: What alternative ways have you thought of to implement you idea? description: There are often multiple ways to do one thing - context is important. - validations: - required: true + validations: + required: true - type: textarea attributes: label: Any additional information From 84473dcd701e57515eb3166ff7c6b9a153431c75 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 15:26:29 +0100 Subject: [PATCH 10/15] feat: Update templates --- .github/ISSUE_TEMPLATE/1-idea_suggestion.yml | 8 +- .github/ISSUE_TEMPLATE/2-bug_report.yml | 84 +++++++++++--------- 2 files changed, 52 insertions(+), 40 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml index 0b72f255b..ff048285c 100644 --- a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml +++ b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml @@ -28,16 +28,16 @@ body: - type: textarea attributes: label: Is this idea related to a larger problem? - description: If you have identified specific issues, it might be part of a design pattern. + description: If you have identified multiple related issues, it might be a design pattern problem. validations: required: true - type: textarea attributes: - label: What alternative ways have you thought of to implement you idea? - description: There are often multiple ways to do one thing - context is important. + label: What alternative ways are there to implement your idea? + description: There are often multiple ways to something - context is important. validations: required: true - type: textarea attributes: label: Any additional information - description: Add any remaining detail for this request not covered by the above questions. + description: Add any remaining detail for this idea not covered by the above questions. diff --git a/.github/ISSUE_TEMPLATE/2-bug_report.yml b/.github/ISSUE_TEMPLATE/2-bug_report.yml index 12a6c787b..f71a3312d 100644 --- a/.github/ISSUE_TEMPLATE/2-bug_report.yml +++ b/.github/ISSUE_TEMPLATE/2-bug_report.yml @@ -1,37 +1,49 @@ ---- name: Bug report -about: Create a report to help us improve -title: "" -labels: "bug" -assignees: "" ---- - -### Describe the bug - -A clear and concise description of what the bug is. - -### To reproduce - -Steps to reproduce the behavior: - -1. Deploy this project using [...] -2. View output/logs/configuration on [...] -3. See error - -### Expected behavior - -A clear and concise description of what you expected to happen. - -### Your environment - -- Version/release of this project or specific commit - -- Target deployment platform - -### Additional context - -Add any other context about the problem here. - -### Sensitive Information - -Remember to redact any sensitive information such as authentication credentials or license keys. +description: Report an issue with our documentation +title: "[Bug]: " +body: + - type: textarea + attributes: + label: Describe the bug you have identified + description: Explain the problem with as much detail as possible. + validations: + required: true + - type: dropdown + attributes: + label: Which product or products does this request relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + attributes: + label: Steps to reproduce the bug + description: Describe the where the issue occurs. + validations: + required: true + - type: textarea + attributes: + label: What is the expected or desired behaviour? + description: Describe what you expected to happen instead of the bug. + validations: + required: true + - type: textarea + attributes: + label: What environments or versions does this bug affect? + description: Describe the contexts which this bug seems to occur. + validations: + required: true + - type: textarea + attributes: + label: Any additional information + description: Add any remaining detail for this idea not covered by the above questions. \ No newline at end of file From 6dea358eb5d85a19fe01e9bbbdeed29f252fdc49 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 15:58:13 +0100 Subject: [PATCH 11/15] feat: Finish converting issue templates to forms --- .github/ISSUE_TEMPLATE/4-story_task.yml | 62 ++++++++++++------- .github/ISSUE_TEMPLATE/5-content_plan.yml | 70 +++++++++------------- .github/ISSUE_TEMPLATE/6-epic_overview.yml | 64 ++++++++------------ 3 files changed, 92 insertions(+), 104 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/4-story_task.yml b/.github/ISSUE_TEMPLATE/4-story_task.yml index b2f7f117d..9f8cdae55 100644 --- a/.github/ISSUE_TEMPLATE/4-story_task.yml +++ b/.github/ISSUE_TEMPLATE/4-story_task.yml @@ -1,24 +1,40 @@ ---- name: Story task -about: This template is for a story or task, encompassing a single work item for completion -title: "" -labels: "documentation" -projects: ["nginxinc/32"] -assignees: "" ---- - -*Remove italicized directions as relevant to reduce noise in the issue description.* - -## Overview - -*Written as a user story*. - -**As a** , **I want** , **So I can** . - -## Description - -*Add the finer details of what this task involves and is trying to accomplish. A problem well defined is half-solved*. - -## Acceptance criteria - -*Add any exacting acceptance criteria for the task to be complete. Start with known hard requirements, since they may create blockers.* \ No newline at end of file +description: This template is for a story or task, encompassing a single work item for completion +title: "[Story]: " +body: + - type: textarea + attributes: + label: Overview + description: Use this section to write user stories. + placeholder: As a** , **I want** , **So I can** + validations: + required: true + - type: dropdown + attributes: + label: Which product or products does this request relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + attributes: + label: Description + description: Add the finer details of what this task involves and is trying to accomplish. + validations: + required: true + - type: textarea + attributes: + label: Acceptance criteria + description: Acceptance criteria are written from a user perspective, and should map to the user stories. + validations: + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/5-content_plan.yml b/.github/ISSUE_TEMPLATE/5-content_plan.yml index d68f7d5c2..091f0475e 100644 --- a/.github/ISSUE_TEMPLATE/5-content_plan.yml +++ b/.github/ISSUE_TEMPLATE/5-content_plan.yml @@ -1,44 +1,28 @@ ---- name: Content release plan -about: This template is for a content release plan, typically tied to a product release -title: " v#.# content release plan" -labels: "documentation" -projects: ["nginxinc/32"] -assignees: "" ---- - -*Remove italicized directions as relevant to reduce noise in the issue description.* - -## Overview - -- **Product name**: -- **Release date**: - -A content release plan establishes and tracks the documentation work for a product related to a release. - -Add tickets to this content release plan as sub-issues, and update it as you go along. - -## Description - -*Write a high-level summary of changes expected in this release*. - -## User stories - -**As a** technical writer, -**I want** a content release plan for my product, -**So I can** ensure correct content is released alongside the latest version of the product. - -**As a** product owner, -**I want** a content release plan for my product, -**So I can** ensure the product team includes documentation as part of changes to the product. - -## Tasks - -*Create a simple list of tasks necessary for this content plan. Finer details can be kept to sub-issues.* -*Each task item should have a 1:1 relationship with a documentation item, which could be an engineering issue.* - -- [ ] Update changelog/release notes -- [ ] Update version reference information (Such as technical specifications, version shortcodes) -- [ ] Update any other documentation impacted by changes in this release -- Additional task 1 -- Additional task 2 \ No newline at end of file +description: This template is for a content release plan, typically tied to a product release +title: " v#.# content release plan" +body: + - type: textarea + attributes: + label: Overview + description: A content release plan establishes and tracks the documentation work for a product related to a release. + validations: + required: true + - type: textarea + attributes: + label: Description + description: Write a high-level summary of changes expected in this release. + validations: + required: true + - type: textarea + attributes: + label: User stories + description: As a , I want , So I can . + validations: + required: true + - type: textarea + attributes: + label: Tasks + description: Create a simple list of tasks necessary for this content plan. Finer details can be kept to sub-issues. + validations: + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/6-epic_overview.yml b/.github/ISSUE_TEMPLATE/6-epic_overview.yml index 53e13124a..f01a64173 100644 --- a/.github/ISSUE_TEMPLATE/6-epic_overview.yml +++ b/.github/ISSUE_TEMPLATE/6-epic_overview.yml @@ -1,40 +1,28 @@ ---- name: Epic overview -about: This template is for planning an epic, which is a large body of effort involving multiple stories or tasks +description: This template is for planning an epic, which is a large body of effort involving multiple stories or tasks title: "" -labels: "epic, documentation" -projects: ["nginxinc/32"] -assignees: "" ---- - -*Remove italicized directions as relevant to reduce noise in the issue description.* - -## Description - -*Write a high-level description of what the body of work for this epic includes.* - -## Goals - -*Describe the intent of the epic and what the intended impact is for this effort.* - -## User stories - -*Add a user story for relevant persona to this epic, who are the stakeholders*. - -**As a** , -**I want** , -**So I can** . - -**As a** , -**I want** , -**So I can** . - -## Tasks - -*Create a simple list of tasks necessary for this epic. Finer details should be kept to sub-issues/tasks/stories.* - -- Example task 1 -- Example task 1 -- Example task 1 -- Example task 1 -- Example task 1 \ No newline at end of file +body: + - type: textarea + attributes: + label: Description + description: Write a high-level description of what the body of work for this epic includes. + validations: + required: true + - type: textarea + attributes: + label: Goals + description: Describe the intent of the epic and what the intended impact is for this effort. + validations: + required: true + - type: textarea + attributes: + label: User stories + description: As a , I want , So I can . + validations: + required: true + - type: textarea + attributes: + label: Tasks + description: Create a simple list of tasks necessary for this epic. Finer details should be kept to sub-issues/tasks/stories. + validations: + required: true \ No newline at end of file From b1bb1242853c8811e8671e5382fd2ac426d31c37 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 16:01:37 +0100 Subject: [PATCH 12/15] fix: Template issues --- .github/ISSUE_TEMPLATE/5-content_plan.yml | 2 +- .github/ISSUE_TEMPLATE/6-epic_overview.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/5-content_plan.yml b/.github/ISSUE_TEMPLATE/5-content_plan.yml index 091f0475e..a5a069e6a 100644 --- a/.github/ISSUE_TEMPLATE/5-content_plan.yml +++ b/.github/ISSUE_TEMPLATE/5-content_plan.yml @@ -17,7 +17,7 @@ body: - type: textarea attributes: label: User stories - description: As a , I want , So I can . + description: As a user, I want thing, So I can action. validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/6-epic_overview.yml b/.github/ISSUE_TEMPLATE/6-epic_overview.yml index f01a64173..bf7aebb87 100644 --- a/.github/ISSUE_TEMPLATE/6-epic_overview.yml +++ b/.github/ISSUE_TEMPLATE/6-epic_overview.yml @@ -1,6 +1,6 @@ name: Epic overview description: This template is for planning an epic, which is a large body of effort involving multiple stories or tasks -title: "" +title: " " body: - type: textarea attributes: @@ -17,7 +17,7 @@ body: - type: textarea attributes: label: User stories - description: As a , I want , So I can . + description: As a user, I want thing, So I can action. validations: required: true - type: textarea From fd350bfd411c3c37eec416b3fd5ea0e10d78de15 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 16:14:06 +0100 Subject: [PATCH 13/15] fix: Attempt to fix template --- .github/ISSUE_TEMPLATE/4-story_task.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/4-story_task.yml b/.github/ISSUE_TEMPLATE/4-story_task.yml index 9f8cdae55..9d2309f2a 100644 --- a/.github/ISSUE_TEMPLATE/4-story_task.yml +++ b/.github/ISSUE_TEMPLATE/4-story_task.yml @@ -6,7 +6,7 @@ body: attributes: label: Overview description: Use this section to write user stories. - placeholder: As a** , **I want** , **So I can** + placeholder: As a user, I want thing, So I can action. validations: required: true - type: dropdown From b0f0bbc71fd525fa8d2d6d527d23a671c9dda825 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 16:21:43 +0100 Subject: [PATCH 14/15] fix: Update story task template --- .github/ISSUE_TEMPLATE/4-story_task.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/4-story_task.yml b/.github/ISSUE_TEMPLATE/4-story_task.yml index 9d2309f2a..cfc534d6b 100644 --- a/.github/ISSUE_TEMPLATE/4-story_task.yml +++ b/.github/ISSUE_TEMPLATE/4-story_task.yml @@ -1,5 +1,5 @@ -name: Story task -description: This template is for a story or task, encompassing a single work item for completion +name: User story +description: This template is for a single story, encompassing a single work item for completion title: "[Story]: " body: - type: textarea From 7e2ca49726bdaa0fec970a5ecc9295d3f74b2cb5 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 10 Oct 2025 17:21:38 +0100 Subject: [PATCH 15/15] feat: Add preparing issue documentation --- documentation/README.md | 23 +++++++++++------ documentation/prepare-issue.md | 46 ++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 8 deletions(-) create mode 100644 documentation/prepare-issue.md diff --git a/documentation/README.md b/documentation/README.md index b23b53fed..8bcb841f6 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -2,22 +2,29 @@ This directory contains the documentation for the NGINX Documentation repository. -It's used by the DocOps team to record how we use our tools and instructions for common tasks. +It's used by the documentation team to record how we use our tools and instructions for common tasks. -There's also documentation around our ways of working, and ideas of significance wider than the scope of an issue or pull request. +There's also documentation for our ways of working, and ideas of significance wider than the scope of an issue or pull request. We maintain this information publicly as part of NGINX's commitment to transparency and open source. If you're interested in contributing to the [NGINX documentation website](https://docs.nginx.com/), check out [CONTRIBUTING.md](/CONTRIBUTING.md). -## Topics +## Content workflows -- [Contributing closed content](/documentation/closed-contributions.md) +- [Set up pre-commit](/documentation/pre-commit.md) - [Git conventions](/documentation/git-conventions.md) -- [Information architecture heuristics](/documentation/ia-heuristics.md) -- [Maintainers etiquette](/documentation/maintainers-etiquette.md) - [Managing content with Hugo](/documentation/hugo-content.md) -- [Proposals](/documentation/proposals/README.md) -- [Set up pre-commit](/documentation/pre-commit.md) - [Using include files](/documentation/include-files.md) +- [Contributing closed content](/documentation/closed-contributions.md) + +## Writing guidance + +- [Information architecture heuristics](/documentation/ia-heuristics.md) - [Writing style guide](/documentation/style-guide.md) + +# Ways of working + +- [Maintainers etiquette](/documentation/maintainers-etiquette.md) +- [Preparing a good issue](/documentation/prepare-issue.md) +- [Proposals](/documentation/proposals/README.md) diff --git a/documentation/prepare-issue.md b/documentation/prepare-issue.md new file mode 100644 index 000000000..6c974c6ae --- /dev/null +++ b/documentation/prepare-issue.md @@ -0,0 +1,46 @@ +# Preparing a good issue + +When [creating a new issue](https://github.com/nginx/documentation/issues/new/choose), many of the templates will guide you to providing important detail. + +We strive to make each issue a single source of truth: as a result, each ticket should contain all of the context required for someone to understand a problem and subsequently be empowered to begin working on it. + +This document exists to explain concepts you may be unfamiliar with, and provide examples of the types and amount of detail preferred. + +## User stories and acceptance criteria + +User stories are written in the following format: + +**As a** \, +**I want** \, +**So I** can \. + +It's written from the perspective of a user, whose priorities are often different from your own. + +The users for each story may map to specific user personas dependent on the required content design complexity. + +A user persona reflects a broad set of demographic criteria, representing a type of person who may have different levels of experience, domain knowledge or priorities. + +Acceptance criteria are used to determine whether or not the need identified as part of a user story is fulfilled. + +Much like the user story, it is the user perspective that defines how acceptance criteria are written. + +Here is a good and bad example of acceptance criteria: + +1. The user can find the information about configuring \ +2. Information about \ has been updated + +The first example focuses on ensuring the work has meaningful impact to help a user. + +The second example is simply a checklist item for managing work, without considering its effectiveness. + +## Design and time constraints + +As part of identifying the scope of changes involved with a particular issue, the maintainer reviewing an issue will need to identify any important constraints. + +Constraints tend to be precise and sensitive in nature, and are used to figure out how a ticket should be prioritized. + +- If an issue involves changing a common noun, it may affect other work priorities +- If an issue is related to an upcoming release, it might need attention soon +- If an issue leaves users in an operable state, it requires intervention immediately + +Clear constraints reduces or removes time that might otherwise be spent clarifying detail around an issue. \ No newline at end of file