Differential D37671 Diff 114047 documentation/content/en/articles/pr-guidelines/_index.adoc

Changeset View

Standalone View

documentation/content/en/articles/pr-guidelines/_index.adoc

Context not available.
	- author: Hiten Pandya	- author: Hiten Pandya
	description: These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs).	description: These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs).
	trademarks: ["freebsd", "general"]	trademarks: ["freebsd", "general"]
	tags: ["PR", "guideline", "bugs", "maintenance", "BugZilla", "FreeBSD"]	tags: ["PR", "guideline", "bugs", "maintenance", "Bugzilla", "FreeBSD"]
	---	---

	= Problem Report Handling Guidelines	= Problem Report Handling Guidelines
Context not available.
	Abstract	Abstract

	These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs).	These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs).
	Whilst developed for the FreeBSD PR Database Maintenance Team mailto:freebsd-bugbusters@FreeBSD.org[freebsd-bugbusters@FreeBSD.org], these guidelines should be followed by anyone working with FreeBSD PRs.	Whilst developed for the FreeBSD PR Database Maintenance Team mailto:freebsd-bugbusters@FreeBSD.org[freebsd-bugbusters@FreeBSD.org], these guidelines should be followed by anyone working with reports.

	'''	'''

Context not available.
	As accurate tracking of outstanding software defects is important to FreeBSD's quality, the correct use of the software is essential to the forward progress of the Project.	As accurate tracking of outstanding software defects is important to FreeBSD's quality, the correct use of the software is essential to the forward progress of the Project.

	Access to Bugzilla is available to the entire FreeBSD community.	Access to Bugzilla is available to the entire FreeBSD community.
	In order to maintain consistency within the database and provide a consistent user experience, guidelines have been established covering common aspects of bug management such as presenting followup, handling close requests, and so forth.	In order to maintain consistency within the database and provide a consistent user experience, guidelines have been established covering common aspects of bug management such as presenting followup and handling close requests.

	[[pr-lifecycle]]	[[pr-lifecycle]]
	== Problem Report Life-cycle	== Problem Report Life-cycle

	* The Reporter submits a bug report on the website. The bug is in the `Needs Triage` state.	* The Reporter submits a bug report on the website.
	* Jane Random BugBuster confirms that the bug report has sufficient information to be reproducible. If not, she goes back and forth with the reporter to obtain the needed information. At this point the bug is set to the `Open` state.	The report has `New` status.
	* Joe Random Committer takes interest in the PR and assigns it to himself, or Jane Random BugBuster decides that Joe is best suited to handle it and assigns it to him. The bug should be set to the `In Discussion` state.	* Jane Random BugBuster confirms that the report has sufficient information to be reproducible.
		If not, she goes back and forth with the reporter to obtain the needed information.
		At this point the status is set to `Open`.
		* Joe Random Committer takes interest and assigns the report to himself, or Jane Random BugBuster decides that Joe is best suited to handle the report and assigns it to him.
		The status should be set to `In Progress`.
	* Joe has a brief exchange with the originator (making sure it all goes into the audit trail) and determines the cause of the problem.	* Joe has a brief exchange with the originator (making sure it all goes into the audit trail) and determines the cause of the problem.
	* Joe pulls an all-nighter and whips up a patch that he thinks fixes the problem, and submits it in a follow-up, asking the originator to test it. He then sets the PRs state to `Patch Ready`.	* Joe pulls an all-nighter and whips up a patch that he thinks fixes the problem, and submits it in a follow-up, asking the originator to test it.
		pauamma_gundo.comUnsubmitted Not Done Inline Actions "follow-up" here, but "followup" above. I'd use one consistently. (Probably "followup" because it occurs much more often.) pauamma_gundo.com: "follow-up" here, but "followup" above. I'd use one consistently. (Probably "followup" because…
	* A couple of iterations later, both Joe and the originator are satisfied with the patch, and Joe commits it to `-CURRENT` (or directly to `-STABLE` if the problem does not exist in `-CURRENT`), making sure to reference the Problem Report in his commit log (and credit the originator if they submitted all or part of the patch) and, if appropriate, start an MFC countdown. The bug is set to the `Needs MFC` state.	He then sets the status to `Patch Ready`.
	* If the patch does not need MFCing, Joe then closes the PR as `Issue Resolved`.	* A couple of iterations later, both Joe and the originator are satisfied with the patch, and Joe commits it to `-CURRENT` (or directly to `-STABLE` if the problem does not exist in `-CURRENT`), making sure to reference the Problem Report in his commit log (and credit the originator if they submitted all or part of the patch) and, if appropriate, start an MFC countdown.
		The status is set to `Needs MFC`.
		* If the patch does not need MFCing, Joe then closes the report as `Fixed`.

	[NOTE]	[NOTE]
	====	====
	Many PRs are submitted with very little information about the problem, and some are either very complex to solve, or just scratch the surface of a larger problem; in these cases, it is very important to obtain all the necessary information needed to solve the problem.	Many reports are submitted with very little information about the problem, and some are either very complex to solve, or just scratch the surface of a larger problem; in these cases, it is very important to obtain all the necessary information needed to solve the problem.
	If the problem contained within cannot be solved, or has occurred again, it is necessary to re-open the PR.	If the problem contained within cannot be solved, or has occurred again, it is necessary to re-open the report.
	====	====

	[[pr-states]]	[[pr-states]]
	== Problem Report State	== Problem Report Status

	It is important to update the state of a PR when certain actions are taken.	It is important to update the status when certain actions are taken.
	The state should accurately reflect the current state of work on the PR.	The status should accurately reflect the current state of work on the report.

	.A small example on when to change PR state	.An example on when to change status
	[example]	[example]
	====	====
	When a PR has been worked on and the developer(s) responsible feel comfortable about the fix, they will submit a followup to the PR and change its state to "feedback".	When a report has been worked on and the developer(s) responsible feel comfortable about the fix, they will submit a followup and change its status to "feedback".
	At this point, the originator should evaluate the fix in their context and respond indicating whether the defect has indeed been remedied.	At this point, the originator should evaluate the fix in their context and respond indicating whether the defect has indeed been remedied.
	====	====

	A Problem Report may be in one of the following states:	A Problem Report may be in one of the following statuses:

	open::	New::
	Initial state; the problem has been pointed out and it needs reviewing.	Initial state; the problem has been pointed out and the report needs reviewing.

	analyzed::	Open::
	The problem has been reviewed and a solution is being sought.	The report has been reviewed and a solution is being sought.

	feedback::	feedback::
	Further work requires additional information from the originator or the community; possibly information regarding the proposed solution.	Further work requires additional information from the originator or the community; possibly information regarding the proposed solution.

	patched::	patched::
	A patch has been committed, but something (MFC, or maybe confirmation from originator) is still pending.	A patch has been committed, but something (MFC, or maybe confirmation from originator) is pending.
		pauamma_gundo.comUnsubmitted Not Done Inline Actions Noting that the status for a patch needing MFC is "patched" here but "Needs MFC" above in the usecase story. pauamma_gundo.com: Noting that the status for a patch needing MFC is "patched" here but "Needs MFC" above in the…

	suspended::	suspended::
	The problem is not being worked on, due to lack of information or resources.	The problem is not being worked on, due to lack of information or resources.
Context not available.
	If the problem cannot be solved at all, it will be closed, rather than suspended.	If the problem cannot be solved at all, it will be closed, rather than suspended.
	The documentation project uses suspended for wish-list items that entail a significant amount of work which no one currently has time for.	The documentation project uses suspended for wish-list items that entail a significant amount of work which no one currently has time for.

	closed::	Closed::
	A problem report is closed when any changes have been integrated, documented, and tested, or when fixing the problem is abandoned.	A problem report is closed when any changes have been integrated, documented, and tested, or when fixing the problem is abandoned.

	[NOTE]	[NOTE]
	====	====
	The "patched" state is directly related to feedback, so you may go directly to "closed" state if the originator cannot test the patch, and it works in your own testing.	The "patched" status is directly related to feedback, so you may go directly to "Closed" if the originator cannot test the patch, and it works in your own testing.
	====	====

	[[pr-types]]	[[pr-types]]
	== Types of Problem Reports	== Types of Problem Report

	While handling problem reports, either as a developer who has direct access to the Problem Reports database or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of PRs.	While handling reports, either as a developer who has direct access or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of report.

	* <<pr-unassigned>>	* <<pr-unassigned>>
	* <<pr-assigned>>	* <<pr-assigned>>
Context not available.
	* <<pr-stale>>	* <<pr-stale>>
	* <<pr-misfiled-notpr>>	* <<pr-misfiled-notpr>>

	The following sections describe what each different type of PRs is used for, when a PR belongs to one of these types, and what treatment each different type receives.	The following sections describe what each different type of report is used for, when a report belongs to one of these types, and what treatment each different type receives.

	[[pr-unassigned]]	[[pr-unassigned]]
	== Unassigned PRs	== Unassigned Reports

	When PRs arrive, they are initially assigned to a generic (placeholder) assignee.	When reports arrive, they are initially assigned to a generic (placeholder) assignee.
	These are always prepended with `freebsd-`.	These are always prepended with `freebsd-`.
	The exact value for this default depends on the category; in most cases, it corresponds to a specific FreeBSD mailing list.	The exact value for this default depends on the category; in most cases, it corresponds to a specific FreeBSD mailing list.
	Here is the current list, with the most common ones listed first:	Here is the current list, with the most common ones listed first:
Context not available.
	\|freebsd-usb	\|freebsd-usb
	\|===	\|===

	Do not be surprised to find that the submitter of the PR has assigned it to the wrong category.	Do not be surprised to find that the submitter of the report has assigned it to the wrong category.
	If you fix the category, do not forget to fix the assignment as well.	If you fix the category, do not forget to fix the assignment as well.
	(In particular, our submitters seem to have a hard time understanding that just because their problem manifested on an i386 system, that it might be generic to all of FreeBSD, and thus be more appropriate for `kern`.	(In particular, our submitters seem to have a hard time understanding that just because their problem manifested on an i386 system, that it might be generic to all of FreeBSD, and thus be more appropriate for `kern`.
	The converse is also true, of course.)	The converse is also true, of course.)

	Certain PRs may be reassigned away from these generic assignees by anyone.	Certain reports may be reassigned away from these generic assignees by anyone.
	There are several types of assignees: specialized mailing lists; mail aliases (used for certain limited-interest items); and individuals.	There are several types of assignees: specialized mailing lists; mail aliases (used for certain limited-interest items); and individuals.

	For assignees which are mailing lists, please use the long form when making the assignment (e.g., `freebsd-foo` instead of `foo`);	For assignees which are mailing lists, please use the long form when making the assignment (e.g., `freebsd-foo` instead of `foo`);
Context not available.

	[NOTE]	[NOTE]
	====	====
	Since the list of individuals who have volunteered to be the default assignee for certain types of PRs changes so often, it is much more suitable for https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki].	Since the list of individuals who have volunteered to be the default assignee for certain types of report changes so often, it is much more suitable for https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki].
	====	====

	Here is a sample list of such entities; it is probably not complete.	Here is a sample list of such entities; it is probably not complete.
Context not available.
	\|mailing list	\|mailing list
	\|===	\|===

	Ports PRs which have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone.)	Ports reports that have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone).
		pauamma_gundo.comUnsubmitted Not Done Inline Actions While here, I'd mention that checking https://cgit.freebsd.org/src/tree/share/misc/committers-{doc,ports,src}.dot is a good way to check which commit bit(s) someone has. pauamma_gundo.com: While here, I'd mention that checking https://cgit.freebsd.org/src/tree/share/misc/committers…

	For other PRs, please do not reassign them to individuals (other than yourself) unless you are certain that the assignee really wants to track the PR.	For other reports, please do not reassign them to individuals (other than yourself) unless you are certain that the assignee really wants to track the report.
	This will help to avoid the case where no one looks at fixing a particular problem because everyone assumes that the assignee is already working on it.	This will help to avoid the case where no one looks at fixing a particular problem because everyone assumes that the assignee is already working on it.

	[[common-assignees-other]]	[[common-assignees-other]]
Context not available.
	\|===	\|===

	[[pr-assigned]]	[[pr-assigned]]
	== Assigned PRs	== Assigned Reports

	If a PR has the `responsible` field set to the username of a FreeBSD developer, it means that the PR has been handed over to that particular person for further work.	If a report has the `responsible` field set to the username of a FreeBSD developer, it means that the report has been handed over to that particular person for further work.

	Assigned PRs should not be touched by anyone but the assignee or bugmeister.	Assigned reports should not be touched by anyone but the assignee or bugmeister.
	If you have comments, submit a followup.	If you have comments, submit a followup.
	If for some reason you think the PR should change state or be reassigned, send a message to the assignee.	If for some reason you think the report should change status or be reassigned, send a message to the assignee.
	If the assignee does not respond within two weeks, unassign the PR and do as you please.	If the assignee does not respond within two weeks, unassign the report and do as you please.

	[[pr-dups]]	[[pr-dups]]
	== Duplicate PRs	== Duplicate Reports

	If you find more than one PR that describe the same issue, choose the one that contains the largest amount of useful information and close the others, stating clearly the number of the superseding PR.	If you find more than one report that describe the same issue, choose the one that contains the largest amount of useful information and close the others, stating clearly the number of the superseding report.
	If several PRs contain non-overlapping useful information, submit all the missing information to one in a followup, including references to the others; then close the other PRs (which are now completely superseded).	If several reports contain non-overlapping useful information, submit all the missing information to one in a followup, including references to the others; then close the other reports (which are now completely superseded).

	[[pr-stale]]	[[pr-stale]]
	== Stale PRs	== Stale Reports

	A PR is considered stale if it has not been modified in more than six months. Apply the following procedure to deal with stale PRs:	A report is considered stale if it has not been modified in more than six months.
		Apply the following procedure to deal with stale reports:

	* If the PR contains sufficient detail, try to reproduce the problem in `-CURRENT` and `-STABLE`. If you succeed, submit a followup detailing your findings and try to find someone to assign it to. Set the state to "analyzed" if appropriate.	* If the report contains sufficient detail, try to reproduce the problem in `-CURRENT` and `-STABLE`.
	* If the PR describes an issue which you know is the result of a usage error (incorrect configuration or otherwise), submit a followup explaining what the originator did wrong, then close the PR with the reason "User error" or "Configuration error".	If you succeed, submit a followup detailing your findings and try to find someone to assign it to. Set the status to "analyzed" if appropriate.
	* If the PR describes an error which you know has been corrected in both `-CURRENT` and `-STABLE`, close it with a message stating when it was fixed in each branch.	* If the report describes an issue which you know is the result of a usage error (incorrect configuration or otherwise), submit a followup explaining what the originator did wrong, then close the report with the reason "User error" or "Configuration error".
	* If the PR describes an error which you know has been corrected in `-CURRENT`, but not in `-STABLE`, try to find out when the person who corrected it is planning to MFC it, or try to find someone else (maybe yourself?) to do it. Set the state to "patched" and assign it to whomever will do the MFC.	* If the report describes an error which you know has been corrected in both `-CURRENT` and `-STABLE`, close it with a message stating when it was fixed in each branch.
	* In other cases, ask the originator to confirm if the problem still exists in newer versions. If the originator does not reply within a month, close the PR with the notation "Feedback timeout".	* If the report describes an error which you know has been corrected in `-CURRENT`, but not in `-STABLE`, try to find out when the person who corrected it is planning to MFC it, or try to find someone else (maybe yourself?) to do it.
		Set the status to "patched" and assign it to whomever will do the MFC.
		* In other cases, ask the originator to confirm if the problem still exists in newer versions.
		If the originator does not reply within a month, close the report with the notation "Feedback timeout".

	[[pr-misfiled-notpr]]	[[pr-misfiled-notpr]]
	== Non-Bug PRs	== Non-Bug Reports

	Developers that come across PRs that look like they should have been posted to {freebsd-bugs} or some other list should close the PR, informing the submitter in a comment why this is not really a PR and where the message should be posted.	Developers that come across reports that look like they should have been posted to {freebsd-bugs} or some other list should close the report, informing the submitter in a comment why this is not really a report and where the message should be posted.

	The email addresses that Bugzilla listens to for incoming PRs have been published as part of the FreeBSD documentation, have been announced and listed on the web-site.	The email addresses that Bugzilla listens to for incoming reports have been published as part of the FreeBSD documentation, have been announced and listed on the web-site.
		pauamma_gundo.comUnsubmitted Not Done Inline Actions While here, no dash. Either "website" or "web site". pauamma_gundo.com: While here, no dash. Either "website" or "web site".
	This means that spammers found them.	This means that spammers found them.

	Whenever you close one of these PRs, please do the following:	Whenever you close one of these reports, please do the following:

	* Set the component to `junk` (under `Supporting Services`.	* Set the component to `junk` (under `Supporting Services`.
		pauamma_gundo.comUnsubmitted Not Done Inline Actions Missing ) pauamma_gundo.com: Missing )
	* Set Responsible to `nobody@FreeBSD.org`.	* Set Responsible to `nobody@FreeBSD.org`.
	* Set State to `Issue Resolved`.	* Set status to `Closed`.

	Setting the category to `junk` makes it obvious that there is no useful content within the PR, and helps to reduce the clutter within the main categories.	Setting the category to `junk` makes it obvious that there is no useful content within the report, and helps to reduce the clutter within the main categories.

	[[references]]	[[references]]
	== Further Reading	== Further Reading
Context not available.
	This is a list of resources relevant to the proper writing and processing of problem reports.	This is a list of resources relevant to the proper writing and processing of problem reports.
	It is by no means complete.	It is by no means complete.

	* extref:{problem-reports}[How to Write FreeBSD Problem Reports]-guidelines for PR originators.	* extref:{problem-reports}[How to Write FreeBSD Problem Reports]-guidelines for originators.
Context not available.