diff options
authorGraham Perrin <grahamperrin@FreeBSD.org>2022-10-29 03:16:34 +0000
committerGraham Perrin <grahamperrin@FreeBSD.org>2022-10-29 03:16:34 +0000
commit03d204adfdf1a7bb586db28e9e83e63ca683a3ad (patch)
parent96e271d0bbb4284378a614d3f6b4578926613a25 (diff)
articles/problem-reports: cease recommending the 'patch' keyword
'Writing FreeBSD Problem Reports' pleads for use of a keyword: patch – https://docs.freebsd.org/en/articles/problem-reports/#pr-writing-tips Keywords 'patch' and 'patch-ready' remain in Bugzilla – https://bugs.freebsd.org/bugzilla/describekeywords.cgi – but should no longer be used. Both keywords are deprecated: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=227147 Update the article: * end the plea * explain why the available keywords should not be used. PR: 267176 Bug report: https://bugs.freebsd.org/267176 Mentors: gjb, carlavilla Reviewed by: gjb Approved by: gjb Differential revision: https://reviews.freebsd.org/D37086
1 files changed, 3 insertions, 1 deletions
diff --git a/documentation/content/en/articles/problem-reports/_index.adoc b/documentation/content/en/articles/problem-reports/_index.adoc
index 81cf7c92f9..fd0f5d343b 100644
--- a/documentation/content/en/articles/problem-reports/_index.adoc
+++ b/documentation/content/en/articles/problem-reports/_index.adoc
@@ -132,7 +132,9 @@ Before we get into the mechanics of the program used to generate and submit PRs,
* _Do not leave the "Summary" line empty._ The PRs go both onto a mailing list that goes all over the world (where the "Summary" is used for the `Subject:` line), but also into a database. Anyone who comes along later and browses the database by synopsis, and finds a PR with a blank subject line, tends just to skip over it. Remember that PRs stay in this database until they are closed by someone; an anonymous one will usually just disappear in the noise.
* _Avoid using a weak "Summary" line._ You should not assume that anyone reading your PR has any context for your submission, so the more you provide, the better. For instance, what part of the system does the problem apply to? Do you only see the problem while installing, or while running? To illustrate, instead of `Summary: portupgrade is broken`, see how much more informative this seems: `Summary: port ports-mgmt/portupgrade coredumps on -current`. (In the case of ports, it is especially helpful to have both the category and portname in the "Summary" line.)
-* _If you have a patch, say so._ A PR with a patch included is much more likely to be looked at than one without. Please set the `patch` Keyword in Bugzilla.
+* _If you have a patch, say so._
+The presence of a patch makes it much easier to progress a report.
+** Do not use the `patch` or `patch-ready` keywords – they are deprecated.
* _If you are a maintainer, say so._ If you are maintaining a part of the source code (for instance, an existing port), you definitely should set the "Class" of your PR to `maintainer-update`. This way any committer that handles your PR will not have to check.
* _Be specific._ The more information you supply about what problem you are having, the better your chance of getting a response.