Bug 206922 - Handbook: Chapter 4.5+ changes
Summary: Handbook: Chapter 4.5+ changes
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Warren Block
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2016-02-04 12:45 UTC by John Marino
Modified: 2016-11-19 23:43 UTC (History)
6 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 2016-02-04 12:45:36 UTC
I can provide changes once the approach is approved.

Chapter 4.5 "Using the Ports Collection" discusses portmaster in an inappropriate way, e.g. "recommended tool for upgrading installed ports".  I do not believe this is accurate (in other words, is it really recommended?  if so, it must be officially maintained).

I suggest the following:
1) remove all references to portmaster from chapter 4.5
2) add a new section either after 4.5 or after 4.6 (poudriere) that describes how to maintain using Synth, which has gotten a lot of testing recently.

It would not belong in 4.5 because it's closer to poudriere than PortUpgrade.

If people agree, I can start working on the text.
Comment 1 Greg Lehey freebsd_committer 2016-02-05 01:07:39 UTC
As long as portmaster is still in the Ports Collection, it doesn't make sense to remove documentation.  Instead it would be a good idea to update the documentation to explain the current status.
Comment 2 John Marino freebsd_committer 2016-02-05 07:33:33 UTC
I have a much strict view of the world.

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.

In my world, this is a *COMPLETELY UNACCEPTABLE* situation.

What other s/w is documented yet unmaintained in FreeBSD?  

There seems to be a feeling that having portmaster unmaintained is ok, and that portmaster has no bugs.  I think neither is the case.

In my world, there are two options:
1) officially support portmaster
2) remove it from documentation

This suggestion, "let's just add a footnote that it's not maintained" is not good one, nor it is a professional one.

Where is the motivation to save this particular piece of software coming from?  And why the pro-portmaster people not maintaining it (assuming they have the ability?)

finally, if getting it out the documentation initiates it removal out the ports collection, I could go for that.  Howver, right now, it doesn't *deserve* to be in the documentation because it as fallen below acceptable maintenance level and I hope everyone realizes that.
Comment 3 Warren Block freebsd_committer 2016-02-05 14:48:07 UTC
At present, portmaster still has no direct competition.  It is a no-dependencies shell script.  portupgrade is the closest thing, but Ruby and ruby-bdb dependencies cause trouble on upgrades.

Package builders like poudriere and synth do not compete in the same space, with higher overhead in dependencies, configuration, disk space, build time, and user interface.

As far as maintenance, nobody wants to maintain dense shell script.  (The reasons for portmaster being in sh are debatable in their own right, but not relevant to this discussion.)

Until there is a close replacement, or portmaster is no longer functional, removing it from the documentation is premature.  That is not a statement on the desirability of the situation, just an instance of BSD pragmatism.
Comment 4 John Marino freebsd_committer 2016-02-05 14:59:19 UTC
(In reply to Warren Block from comment #3)

"At present, portmaster still has no direct competition.  It is a no-dependencies shell script.  portupgrade is the closest thing, but Ruby and ruby-bdb dependencies cause trouble on upgrades."

1) I disagree about the competition
2) it's irrelevant.  You can't recommend it officially and not have it maintained, period.

"As far as maintenance, nobody wants to maintain dense shell script.  (The reasons for portmaster being in sh are debatable in their own right, but not relevant to this discussion.)"

Au contraire, it's the heart of the discussion.  No maintainer, get it out of the documentation ASAP.

"Until there is a close replacement, or portmaster is no longer functional, removing it from the documentation is premature.  That is not a statement on the desirability of the situation, just an instance of BSD pragmatism."

It has a man page, it doesn't need to be in the freebsd handbook.

################################################

There is a serious catch-22 going on.
The portmgr doesn't want to deprecate it as long as it is in documentation, and the docs guys don't want to remove it as long as it is in ports.  

Both desires cannot exist.

you do NOT want new users of portmaster in this state.  You are not doing them any service as all.

Why is the concept even a discussion?  How can you RECOMMEND non-maintained buggy software in the official handbook?  Whether or not it has competition is irrelevant.
Comment 5 Martin Wilke freebsd_committer 2016-02-07 15:17:02 UTC
Portmgr never have said it is because of the documentation, we have said its widely used, in additional synth have tons of dependency, not widely tested yet, and it is to be honest just added since January 2016 to the ports. Not to forget its only available for x86 platforms. In other words synth can not be a replacement for portmaster yet.
Comment 6 John Marino freebsd_committer 2016-02-07 15:24:13 UTC
listen to me carefully this time:

1) This PR is not about "replacing" portmaster.
It is about REMOVING portmaster from the handbook because it is not meeting quality requirements

2) It also about planning where to document synth.  That's a separate issue.

3) You comment about wide testing is now false.  Please stop spreading fud.  And for extra credit, try it.

4) POUDRIERE can REPLACE portmaster on EVERY platform.

5) The "lots of dependencies" is FUD too. There's 1 unique dependency that takes 10 minutes to build on a machine that 4 years old.  Everything else is common to other ports, almost all common to lang/gcc which everyone needs.

Please focus on the actual topic.  Forget about Synth and pretend it does not exist.  Even in that case, portmaster has failed to meet quality requirements and should be removed from the handbook, PERIOD.
Comment 7 Martin Wilke freebsd_committer 2016-02-07 15:31:26 UTC
(In reply to John Marino from comment #6)

Can you please less aggressive?

5) In ports-svn not just me pointed out that portmaster still runs fine for a lot of peoples, on a single server env peoples prefers a single tool without any dependency.

So please don't tell everyone its broken just because it is not running for your usage cases.
Comment 8 John Marino freebsd_committer 2016-02-07 16:04:45 UTC
I'm not the one that enter the PR and starting spewing FUD and red herrings.  You joined on your own accord.

Do we need to get Core to make policy on whether or not UNMAINTAINED system can be documented in the handbook?

Are you speaking for portmgr?  In other words, are you saying portmgr is publicly declaring that unmaintained software is suitable for the handbook?

What is portmgr OFFICIAL position documentation requirements?  It might be helpful to know because I absolutely dumbfounded that there is even a debate on this.



P.S. The "some body prefer no-dep tools" is also fud.  
pkg install synth installs a small package, and it's available on all synth-supported platforms.  Or are you, as portmgr, telling people not to use official package binaries?  As I explained before, if somebody is really crazy about building everything themselves, you could bootstrap synth anyway ("pkg ins synth, then build synth with synth and replace it").  Don't tell me that's not an acceptable response to an already unreasonable position.  It's completely valid so I REALLY don't want to hear any more FUD about single dep b/c 1) it's not a requirement and 2) there are already options that satisfy that and 3) portmaster is still in the tree.
Comment 9 Warren Block freebsd_committer 2016-02-08 01:11:17 UTC
I have modified the Handbook for accuracy, removing the questionable "recommended" wording.
Comment 10 John Marino freebsd_committer 2016-02-08 01:15:04 UTC
If there is not a big red warning block present, then I don't consider the matter closed.  It doesn't address the main concern:  New users are not being informed properly and frankly misled.
Comment 11 John Marino freebsd_committer 2016-02-08 01:39:20 UTC
not to mention this was closed without addressing part 2.
Comment 12 Warren Block freebsd_committer 2016-02-08 01:55:45 UTC
#2 being adding documentation for Synth?  That is best handled separately.  If you have documentation but need help with markup, please post to the freebsd-doc mailing list.
Comment 13 Julian Elischer freebsd_committer 2016-02-08 08:02:26 UTC
The criteria for what should be done is simple.
If it makes the handbook more useful, keep it.
if it makes the handbook more dangerous or misleading, fix or remove it.

in this case, the answer is pretty  clear because a LOT of people still use portmaster and portmaster still works well enough for many people.. especially people looking for a minimal system. Having said that the whole packages/ports question is a shifting landscape.
Comment 14 John Marino freebsd_committer 2016-02-08 10:03:01 UTC
Julian, I could go along with your logic *if* there were disclaimers and warnings, which there are not.

I'd also like to point out that everyone involved in this PR thus far is "pro-portmaster" and clearly biased.  I think this PR was closed pretty hastily.  Changing "recommended" to "small" doesn't provide full disclosure.

I had portmaster "deprecated" (without expiration) that would have provided the disclosure, but it reverted.   Partly using the fact that PM was documented in handbook

This started because of that deprecation, and the presence of documentation came out.  I'm fine with the documention -as is- if the port is against provided with warnings so the users are informed.  If the port doesn't have the warnings, then at least the documenation should.  Not having it anywhere is a diservice for uninformed users.

Do people disagree with that premise?
Comment 15 Julian Elischer freebsd_committer 2016-02-08 11:28:16 UTC
why should it be deprecated?
Comment 16 John Marino freebsd_committer 2016-02-08 11:56:14 UTC
because it has no maintainer, it has not had a *any* maintainer in 9 months, it was abandoned by original author 4 years ago and nobody is caring for the bug reports that are being issued against it.

I have to assume there are people not to file bug reports now because 1) it's got no listed maintainer and 2) previous reports have gone untended

So known bugs, known inability to support modern ports tree, no maintainer, and very few candidates qualified to be maintainer (and nobody wants to do it).

I think that's sufficient reason to mark it deprecated.
Comment 17 Julian Elischer freebsd_committer 2016-02-08 16:08:12 UTC
Firstly 9 months is a tiny amount of time..
secondly what would you use to replace it?
(the good thing about shell is that it's always there)
Comment 18 John Marino freebsd_committer 2016-02-08 16:16:59 UTC
Julian, my position is that if a port is RECOMMENDED in the handbook, then it cannot be allowed to be unmaintained, not for one minute.  IMO, it has to be removed from handbook or a new maintainer found.

Secondly, 9 months is misleading.  It was abandoned 4 years ago.  Bryan Drewery kept it working at a bare minimum but did not addressed numerous bugs.  It's a stretch to call it "maintained" during that period.  I can speculate that he felt somebody needed to do it until poudriere was mature.

As for what to replace it with: This is a red herring.  You don't have to replace it with anything.  If it fails to meet quality requirements, then remove it or at least mark it as such.

In practical terms, poudriere can "replace it" on all platforms.  People say it can't but it can.  I think the problem is people think the rebuilds aren't necessary (in part because portmaster doesn't do them erroneously)

What I've learned today and yesterday is people are more focused on process that end result, and if the process is different than portmaster they think it's bad, even if the end result is superior.  what that outlook, neither poudriere nor synth is a replacement despite providing superior results.
Comment 19 John Marino freebsd_committer 2016-02-08 16:25:40 UTC
by the way, this "shell"/zero-dep topic is indicative of people thinking they understand what's going on without taking even 60 seconds to look at way is really going on.

I know where it comes from: portupgrade and the inbuilt ruby database.

That doesn't apply to either poudriere or synth.  Synth also has no database, and queries pkg(8) for all data.  You can remove every trace of synth and it's repository from a system in a instant and nothing will be affect.  pkg(8) will continue to work, ports will continue to work, the pkg(8) sqlite database remains intact.

So this "OMG, SYNTH HAS BUILD DEPENDENCIES" fear-mongering is baloney with no technical basis, and I've already issued a challenge to prove me wrong.  (Nobody will take me up on it because they can't and it will expose their expertise).

So I'm making an overview diagram because I think people have misconceptions that only a picture can dispell.
Comment 20 Bryan Drewery freebsd_committer 2016-02-08 17:18:46 UTC
(In reply to John Marino from comment #19)
> by the way, this "shell"/zero-dep topic is indicative of people thinking
> they understand what's going on without taking even 60 seconds to look at
> way is really going on.
> 
> I know where it comes from: portupgrade and the inbuilt ruby database.

And even this is a very old issue that is no longer true really. The only problem with portupgrade using ruby is when upgrading ruby. The db issues were fixed long ago by me.

People generally just hate dependencies. I gave up trying to convince them otherwise.
Comment 21 John Marino freebsd_committer 2016-02-08 17:23:26 UTC
I'm glad you are here, Bryan.

Can you glance at this graphic: 
http://downloads.dragonlace.net/misc/synth-img/synth-arch.png

It's meant to show how misplaced *BUILD* dependencies are, at least wrt to Synth.  I tried to convey that Synth is not in any critical path.

Do you think I succeeded?
Comment 22 Kurt Jaeger freebsd_committer 2016-02-08 21:47:30 UTC
Discussing in a PR seems odd. Wouldn't be -ports or -doc be a better place to discuss ?