Bug 194721 - PR documentation wrong says it's okay to submit PRs to notify about newer versions in ports
Summary: PR documentation wrong says it's okay to submit PRs to notify about newer ver...
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Allan Jude
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2014-10-31 20:05 UTC by John Marino
Modified: 2015-03-22 19:29 UTC (History)
5 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description John Marino freebsd_committer 2014-10-31 20:05:23 UTC
The ports bugzilla policy is that PRs are not to be submitted to "helpfully" tell maintainers and/or ports@ mailing list that new versions are available.  Yet Kevin Thompson has notified me that the PR documentation says exactly the opposite, and I confirmed it:

https://www.freebsd.org/doc/en/articles/problem-reports/pr-when.html

Chapter 2:
    Some cases where it may be appropriate to submit a problem report about something that is not a bug are:
    * Notification of updates to externally maintained software (such as ports or software in the contrib/ directory).


Please remove this line immediately.  It reflects exactly opposite of what is acceptable for a ports PR.
Comment 1 Andrew Berg 2014-11-02 14:51:45 UTC
In addition to removal of that line, I would suggest that the third line:

If the port is maintained, PRs announcing new upstream releases are usually not very useful since they generate supplementary work for the committers, and the maintainer likely knows already there is a new version, they have probably worked with the developers on it, they are probably testing to see there is no regression, etc.

be reworded to say that portscout makes announcement of updates unnecessary, but submitting patches to update ports instead of just announcing the update is welcome.
Comment 2 John Marino freebsd_committer 2015-02-08 08:17:28 UTC
bugzilla has been in operation for several months, yet this obsolete "When to Submit a Problem Report" documentation has not been updated since GNATS times.

It's very visible page.  I would think it would be pretty high priority to update this.  Is bugmeister or somebody else working on it already?
Comment 3 Allan Jude freebsd_committer 2015-03-18 17:15:19 UTC
Pending review/approval: https://reviews.freebsd.org/D2092
Comment 4 Andrew Berg 2015-03-18 17:39:29 UTC
(In reply to Allan Jude from comment #3)
(commenting here since reviews.freebsd.org is read-only to me)

It is not obvious to newcomers what "software in the contrib/ directory" is. Rather than:
 <para>When submitting a PR about externally maintained software
 (such as ports or software in the contrib/ directory) consider
 the following:</para>
I suggest:
 <para>When submitting a PR about software not written by FreeBSD
 contributors, consider the following:</para>

I don't think that sentence needs much more clarification than that since the section below outlines the difference between things in base that are native, things in base that are contributed, and things in ports.

The paragraph on portscout doesn't seem to flow well, and I would suggest this:
 <para>If the port is maintained, PRs announcing new upstream
 releases are usually not very helpful since maintainers
 are automatically notified by <application>portscout</application>,
 which automatically tracks new versions of applications, and so
 a PR would only create supplementary work for the committers.</para>
Comment 5 Allan Jude freebsd_committer 2015-03-18 20:38:42 UTC
DR Updated
Comment 6 commit-hook freebsd_committer 2015-03-22 19:28:24 UTC
A commit references this bug:

Author: allanjude
Date: Sun Mar 22 19:28:19 UTC 2015
New revision: 46364
URL: https://svnweb.freebsd.org/changeset/doc/46364

Log:
  Update PR article to ask people not to submit PRs about outdated ports

  PR:		194721
  Differential Revision:	https://reviews.freebsd.org/D2092
  Submitted by:	marino (original)
  Reviewed by:	wblock, Andrew Berg (earlier version)
  Approved by:	bcr (mentor)
  Sponsored by:	ScaleEngine Inc.

Changes:
  head/en_US.ISO8859-1/articles/problem-reports/article.xml