From 1281753be009564723a2fcbe4de2eea3b5028008 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 14 Nov 2025 17:02:15 +0000 Subject: [PATCH] feat: Update issue and overview process documentation This commit re-orders the issue templates, adds examples of issues and guidance on what templates should be used. It also adds a reference to the nginx.org content pipeline documentation that was stored in the folder but not linked from the newer index. --- .../{3-general_request.yml => 1-general_request.yml} | 0 .../{1-idea_suggestion.yml => 3-idea_suggestion.yml} | 0 documentation/README.md | 1 + documentation/prepare-issue.md | 9 +++++++++ 4 files changed, 10 insertions(+) rename .github/ISSUE_TEMPLATE/{3-general_request.yml => 1-general_request.yml} (100%) rename .github/ISSUE_TEMPLATE/{1-idea_suggestion.yml => 3-idea_suggestion.yml} (100%) diff --git a/.github/ISSUE_TEMPLATE/3-general_request.yml b/.github/ISSUE_TEMPLATE/1-general_request.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/3-general_request.yml rename to .github/ISSUE_TEMPLATE/1-general_request.yml diff --git a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml b/.github/ISSUE_TEMPLATE/3-idea_suggestion.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/1-idea_suggestion.yml rename to .github/ISSUE_TEMPLATE/3-idea_suggestion.yml diff --git a/documentation/README.md b/documentation/README.md index 1b21f3547..0895679e7 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -19,6 +19,7 @@ If you're interested in contributing to the [NGINX documentation website](https: - [Using include files](/documentation/include-files.md) - [Contributing closed content](/documentation/closed-contributions.md) - [Review deprecated content](/documentation/deprecated-content.md) +- [nginx.org content](/documentation/nginx-org-source.md) ## Writing guidance diff --git a/documentation/prepare-issue.md b/documentation/prepare-issue.md index d7416092e..5857bb845 100644 --- a/documentation/prepare-issue.md +++ b/documentation/prepare-issue.md @@ -6,6 +6,15 @@ We strive to make each issue a single source of truth: as a result, each ticket This document exists to explain concepts you may be unfamiliar with, and provide examples of the types and amount of detail preferred. +Here are examples of well-formed issues using the templates: + +- [\[Request\]: Clarify NGINX configuration limitations for F5 WAF for NGINX](https://github.com/nginx/documentation/issues/1436) +- [\[Story\]: Replace examples of sensitive values with explicit placeholders](https://github.com/nginx/documentation/issues/1363) + +*General request* and *Bug report* are the most common issue types, with *Documentation idea* available for conceptual improvements. + +The *User story* and *Content release plans* are largely for maintainer use, though we do have [guidance for user stories](#user-stories-and-acceptance-criteria) in this document. + ## Use active voice Much like writing user-facing documentation, we prefer [active voice](https://developers.google.com/tech-writing/one/active-voice) when describing an issue.