From nobody@FreeBSD.org  Tue Oct 27 04:00:27 2009
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id D8533106566B
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 27 Oct 2009 04:00:27 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id C61618FC1A
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 27 Oct 2009 04:00:27 +0000 (UTC)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.3/8.14.3) with ESMTP id n9R40R2v099001
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 27 Oct 2009 04:00:27 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.3/8.14.3/Submit) id n9R40R3r099000;
	Tue, 27 Oct 2009 04:00:27 GMT
	(envelope-from nobody)
Message-Id: <200910270400.n9R40R3r099000@www.freebsd.org>
Date: Tue, 27 Oct 2009 04:00:27 GMT
From: Allan Stokes <aepalea@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: many papercut omissions on portupgrade man page
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         140008
>Category:       ports
>Synopsis:       ports-mgmt/portupgrade: many papercut omissions on portupgrade man page
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-ports-bugs
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Oct 27 04:10:01 UTC 2009
>Closed-Date:    Tue Aug 14 18:40:01 UTC 2012
>Last-Modified:  Tue Aug 14 18:40:01 UTC 2012
>Originator:     Allan Stokes
>Release:        6.4 installed; 7.2 man page online
>Organization:
>Environment:
NA
>Description:
I seem to be upgrading everything this week: OpenBSD, FreeBSD, Ubuntu, Snow Leopard, Resident Evil.  The point here is that FreeBSD is not getting 100% of my focus, and I wish the portupgrade man page was being more considerate of my scattered attention.

I really like the Ubuntu concept of a papercut bug: bugs that affect new users or casual users out of proportion to the effort of fixing them, which I think is the case here, if we consider the role of a seagull sysadmin.

I'll take this in reading order, rather than by importance.

 >> Do not be lazy about backing up your precious data and configuration
 >> files, including the package database in ``/var/db/pkg''.
 
 So give me the full list, and I'll whip up a script; no list == no time just now.
 
 >> --batch
 >> Run an upgrading process in a batch mode (with BATCH=yes).
 
 I imagine that somewhere in the pkgtools BATCH=yes is documented.  (Later: no it's documented in ports(7)).  Does this allow me to run a large package upgrade without those screen prompts?  Throw me a bone here.  (Later: ports(7) says this restricts the  ports to those not requiring interaction [and recursive implications?], which is not what I would have guessed.)
 
 >> --F
 >> --fetchonly
 
 Despite good efforts to document -R elsewhere, it's left out where the harried admin most needs to find it.
 
 >> --interactive
 
 There's a strange trailing Pp in the associated text.  Does not mention -y or -n.  Do these go together with --interactive?  If you read the fine print, cross referencing all three entries, the answer is clear.
 
 >> --keep-going
 >> Force the upgrade of a package even if some of the
 >> requisite packages have failed to upgrade in advance.
 
 Does it have an effect in --fetchonly mode?  Nothing changes in -P mode or -PP mode?  Does it influence --noexecute?
 
 From 6.4 installation:
 >> --config
 >> Run ``make config-conditional'' before everything
 >> for all tasks.  -w option below.
 
 Apparently removed in 7.2.  Good.  I had no clue what it meant.  Was it some variant on BATCH mode?
 
 >> -l FILE
 >> --results-file FILE
 >> Specify a file name to save the results to.
 >> By default, portupgrade does not save results as a file.
 
 And what will this file contain?  All I got under 6.4 was a single line per package error, of the following form.
 
 ! security/sudo (sudo-1.6.9.12)	(clean error)
 
 I was looking for some way to track progress as it grinds through 120 packages so I could manage around other activities.  I was able to check timestamps on files in /var/db/pkg last night, but today after my portsnap upgrade, all the time stamps are ide ntical, even though I've had portupgrade running for hours now.
 
 >> --log-file FORMAT
 >> Specify a printf(3) style format to determine the
 >> log file name for each port.
 
 Again a little light on the expected contents.  Same as what I see on the console?  My harried interpretation was that -l was going to give me a concatenated --log-file  I didn't properly interpret the undefined term "results".
 
 >> --package
 >> Build a package when each specified port is
 >> installed or upgraded.
 
 Build a package where?  Does this mean the install occurs from the built package instead of the default method?  Does that change anything?  What happens if a package file by the same name already exists?
 
 Suggest adding "See PACKAGE in the ENVIRONMENT section."
 
 >> -s
 >> --sudo
 >> Run commands under sudo(8) where needed.
 
 Does this interfere with starting portupgrade in background?  I realize ^Z doesn't work.  Does "commands" include all necessary access to /var/db tree?
 
 If there are no drawbacks to this, why not add under DESCRIPTION: "If you have sudo configured (you should), it's recommended to run portupgrade as a regular user with the -s option".  Web documentation shows portupgrade running at the # prompt, so I ass umed that was best practice.
 
 Under --batch, you might add "If you are running a large update, and your sudo credentials time out, you might want to run portupgrade under sudo or from the root prompt instead of using -s."  If batch has unattended semantics (which I haven't figured out yet).
 
 >> --yes
 >> Answer yes to all the questions.  This option
 >> implies -v and negates -n.
   
 *The* questions?  You mean not the harassment configuration screens asking about LDAP and such like?  The go/no-go questions about final installation, which I infer after cross-referencing back to -n and its long form --no-execute?
 
 Kudos for the TECHNICAL DETAILS section.  But it's not a good resource for the harried admin trying to get wheels turning while heavily multitasking.
 
 The mode I was looking for is this: do everything possible as if I was downloading pre-built binary packages and don't stop until there's nothing left to be done that can't be done without my attention.
 
 Then give me a nice summary of all the defaults I've accepted, in case I later wish to assert a preference, when I have the brain space to do so.
 
 Other suggestions
 
 In the options that mention "make clean" or "make distclean" add "See ports(7)."
 
 Make it more clear in which phase "make config" is run and how to avoid dialog(1) from grinding things to a halt.
 
 In my 6.4 version of ports(7) I see documentation for BATCH and INTERACTIVE.  This doesn't appear to be the same "interactive" as portupgrade.  Is the INTERACTIVE mode of ports available from portupgrade?
 
 And why doesn't ports have an option to "just do it the same as if I loaded the binary package?"  I don't see one.  I don't get why the binary packages can perform default build steps where ports can not.  From a multitasking perspective, I'd rather have the default build complete in background and only pay if I decide to change it later.
 
 My original preference was binary packages, but they weren't available for my aging installation.
 
 Compiling these suggestions took about 20 times more focus than I had last night, when all I wanted to do was quickly get the wheels turning on a potentially long running job.
 
>How-To-Repeat:
Leave network unattended for over a year.  Allocate a few days to upgrade everything all at once.

>Fix:
>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->ruby 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Tue Oct 27 05:40:09 UTC 2009 
Responsible-Changed-Why:  
make this a ports PR and assign.  While here, try to recover the formatting. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=140008 
Responsible-Changed-From-To: ruby->pgollucci 
Responsible-Changed-By: pgollucci 
Responsible-Changed-When: Thu Sep 9 23:11:43 UTC 2010 
Responsible-Changed-Why:  
I will take it 

http://www.freebsd.org/cgi/query-pr.cgi?pr=140008 
Responsible-Changed-From-To: pgollucci->freebsd-ports-bugs 
Responsible-Changed-By: pgollucci 
Responsible-Changed-When: Fri Sep 24 06:22:37 UTC 2010 
Responsible-Changed-Why:  
going to have enotime for the next 2 weeks, sorry 

http://www.freebsd.org/cgi/query-pr.cgi?pr=140008 
Responsible-Changed-From-To: freebsd-ports-bugs->ruby 
Responsible-Changed-By: steve 
Responsible-Changed-When: Mon Jan 3 17:24:22 UTC 2011 
Responsible-Changed-Why:  
Over to maintainer(s). 

http://www.freebsd.org/cgi/query-pr.cgi?pr=140008 
State-Changed-From-To: open->suspended 
State-Changed-By: pgollucci 
State-Changed-When: Wed Feb 22 05:23:45 UTC 2012 
State-Changed-Why:  
Over to maintainer. 


Responsible-Changed-From-To: ruby->freebsd-ports-bugs 
Responsible-Changed-By: pgollucci 
Responsible-Changed-When: Wed Feb 22 05:23:45 UTC 2012 
Responsible-Changed-Why:  
Over to maintainer. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=140008 
State-Changed-From-To: suspended->open 
State-Changed-By: crees 
State-Changed-When: Thu Apr 12 10:03:17 UTC 2012 
State-Changed-Why:  
This should not be suspended. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=140008 

From: Bryan Drewery <bryan@shatow.net>
To: bug-followup@FreeBSD.org, aepalea@gmail.com
Cc: Steve Wills <swills@FreeBSD.org>
Subject: Re: ports/140008: ports-mgmt/portupgrade: many papercut omissions
 on portupgrade man page
Date: Sat, 28 Jul 2012 09:19:17 -0500

 This is an OpenPGP/MIME signed message (RFC 2440 and 3156)
 --------------enig259B0BAF9758DD643B5F2C87
 Content-Type: text/plain; charset=ISO-8859-1
 Content-Transfer-Encoding: quoted-printable
 
 Hi,
 
 These questions are better suited for a forum or mailing list.
 
 There's already extensive documentation on portupgrade.
 
 I've added some of your suggestions for the next release.
 
 If you have more specific additions or see bugs in the manpages, please
 submit another report.
 
 Regards,
 Bryan Drewery [maintainer]
 
 
 
 --------------enig259B0BAF9758DD643B5F2C87
 Content-Type: application/pgp-signature; name="signature.asc"
 Content-Description: OpenPGP digital signature
 Content-Disposition: attachment; filename="signature.asc"
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.10 (MingW32)
 Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
 
 iQIcBAEBAgAGBQJQE/TlAAoJEG54KsA8mwz5HYoP/A4PvQuROzB5SC564gRVuqso
 sAeKe++9Iutu1dypgeRbYnygdgskaG50h5bFaGeh6flF8I2NBEiKoF6j2q+6Atbw
 Rmznloy1ua2KGpd9OGtqGZ/R+oiTmWZ6obwSlMH8+tEQeIuCndnu5Qmv8+ZKu0ti
 iVG5csb7hNDIBd5XejecMjum3pDIeoZYmR4LpBqXhSvbJ6koDQFn1jMxYybVgnqo
 ywJcjJjCSo8f3EiuVLdBwiXk/WQBd2t86uTZlnMa5Vg8ZfnE27RbjVeqidY2P6A8
 eK1nLJ7Aos+FtMKnHEYHTwQ3FKvj7togfUrOVRQKJ3ULmmRE2WraL4t4BLd2qSeO
 rcRgbMtUkcPQQOF2iz93VnVSWANCU4WEH5jguiBXYw2AboueG61aicc0UnQ56qB7
 JTFMC0L5dJhQeHsN4txpU/mHvoI0qufa9ZvuVp8Dz2yYDRFXf6toYhIRETY57+HY
 NGEV7iGQDIlHAJ2z7EXNj3BLOusLWDQpo5BZspZuOKzWtCfOsPRFLlioA4K4VFIv
 vRSsV3Yqoef4kaql+r/0BKf5cGyOIlnSkmdSrXqrchzOAJH6Ui8nylo2bYsi3dmh
 r/CUKRRa0DQ1YVIUrYTC9+PoGe/WwFiNQRSa1x3F2IDOf1xzxVjY8zbL4pS5NAmA
 LsDqqHavH6M/q6n4e4LF
 =cgcH
 -----END PGP SIGNATURE-----
 
 --------------enig259B0BAF9758DD643B5F2C87--
State-Changed-From-To: open->closed 
State-Changed-By: bdrewery 
State-Changed-When: Tue Aug 14 18:40:00 UTC 2012 
State-Changed-Why:  
Thank you for the input. Will expand on manpage entries for next release 
with suggestions given. If you have further suggestions please report 
them to http://pkgtools.github.com. If you have any questions please 
inquire on the ports@ mailing list or FreeBSD forums. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=140008 
>Unformatted:
