Removing documentation (was: [Bug 206922] Handbook: Chapter 4.5+ changes)

[Baptiste Daroussin]

On Sun, Feb 07, 2016 at 11:03:04AM +1100, Greg 'groggy' Lehey wrote:
> I'm bringing this to the attention of the ports community to try to
> come up with a consensus about how to handle existing documentation
> for ageing packages, in this case portmaster.
> 
> This bug report suggests removing the documentation for portmaster
> because it is out of date and no longer maintained.
> 
> But it's still in the ports tree, and people still use it.  The
> current wording (4.5.3.1) claims it is the recommended tool, which is
> clearly out of date.  marino@ (the submitter) writes:
> 
> On Friday,  5 February 2016 at  7:33:33 +0000, bugzilla-noreply at freebsd.org wrote:
> >
> > You have a tool presented as "official" that hasn't had it's
> > original maintainer in 4 years and was only kept on life support up
> > until 9 months ago.
> 
> Agreed, the "official" (the term used is "recommended") status is
> gone.  But that's a reason to fix the documentation, not remove it.
> As I see it, we have three choices, in increasing order of
> desirability:
> 
> 1.  Remove all mention of portmaster.  That's what this PR recommends.
> 2.  Do nothing.
> 3.  Update the documentation to indicate the current status,
>     recommending alternatives if possible.
> 
> The real issue here is that we shouldn't remove documentation for
> software that is still available.  In addition, wblock@ writes:
> 
> On Friday,  5 February 2016 at 14:48:07 +0000, bugzilla-noreply at freebsd.org wrote:
> >
> > At present, portmaster still has no direct competition...
> 
> More generally, the way I see it is simple: we should try to keep the
> documentation as up-to-date as possible.  This means that we don't
> remove documentation for existing packages.  It also means that we may
> need to change the content of the documentation if the status (not
> necessarily the content) of the package changes.
> 
> One of the arguments for removing it from the handbook is that it has
> a man page.  That has some merit, but it doesn't help the people who
> have used portmaster and now don't know what to do.  Even if portmgr
> is deprecated, the documentation should suggest a replacement.
> 
> Can portmgr@ come up with a clear, easy-to-understand policy?
> 

In my opinion there is no reason to remove the mention of portmaster in the
handbook as long as it is not "official" and "recommended" but just listed as a
possible tools.

There are plenty of documentation on the handbook to explain how to use $third
party tools.

portmaster has some design flaws and clearly synth has a way better and safer
one. But that does not mean portmaster is ready to go away as there are plenty
of users using it still and for some cases, no alternative is available.

For instance, as far as I know synth is not available on non i386/amd64
architectures which is imho the major issue for being a candidate for a
replacement of portmaster.

As much as I don't like the way portmaster (and portupgrade) are designed: aka
unsafe building, there are still IMHO no alternative by the fact that an
alternative should cover all our supported architectures. For i386/amd64 users
yes synth is a viable alternative and a way safer one. Also note that synth is
still very young and before pushing anything that would kill others, it would be
good to be more patient and and see how the tool behave/is adopted/is maintained
over the time.

Regarding portmaster, I think it would be time to deprecate it and remove it
from the ports tree/documentation the day when it prevents us from adding an
important feature into the ports tree, which may or may not happen soon.

Out of my mind such features could be:
- subpackages
- flavours/variant

Note that the above would require changes in all the port management tools. Also
note that as far as I know noone is working on the first (subpackages) and
someone picked up the work on flavours/variants based on where I stopped but I
don't think it will land in the ports tree any time soon. (also note I'm not
working on those feature anymore for now, because of ENOTIME :()

BTW: just a clarification on the dependency front:
- at runtime synth depends on only 1 port: ncurses
- at bulidtime it depends on 2 ports: ada (gcc-aux)/ncurses (gcc-aux itself my
  drag other build dependency.

Best regards,
Bapt
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-ports/attachments/20160209/ebfc2f40/attachment.sig>