State of the Porters' Handbook

[Baptiste Daroussin]

On Mon, Oct 28, 2013 at 04:04:58PM +0100, Michael Gmelin wrote:
> On Mon, 28 Oct 2013 15:56:46 +0100
> Baptiste Daroussin <bapt at FreeBSD.org> wrote:
> 
> > On Mon, Oct 28, 2013 at 11:40:50AM +0100, Dominic Fandrey wrote:
> > > On 28/10/2013 11:26, John Marino wrote:
> > > > On 10/28/2013 11:16, Dominic Fandrey wrote:
> > > >> On 28/10/2013 11:03, John Marino wrote:
> > > >>> If there are files in those directories, they'll be on the
> > > >>> plist and stage handles them.  I'd have to look up how to
> > > >>> create empty directories properly.
> > > >>
> > > >> Stage replaceses strings in installed files?
> > > > 
> > > > No, the port does that kind of thing in the stage directory.
> > > > After everything is installed there in the stage directory, they
> > > > are packaged or installed into the $PREFIX
> > > > 
> > > >> I can see the benefits for less error prone package building.
> > > >> But right now it's just additional work coming my way.
> > > > 
> > > > You really need to get a better grasp of the concept.  There are
> > > > several emails from bapt that may help.  For new ports it's not
> > > > "additional" work and for existing ports, yes there is a
> > > > conversion but the benefits are worth it.
> > > > 
> > > >>> 2. Stage is not going away.  There is not another option.
> > > >>> 3. You've been given a source of documentation.  It's not in the
> > > >>> handbook, but it does exist in some form.  What more do you
> > > >>> need to progress?
> > > >>
> > > >> There is a procedure. Stuff belongs into the handbook. Stick to
> > > >> it.
> > > > 
> > > > Fine, but it's a huge topic that somebody has to write and
> > > > validate. You're willing to criticize (justified) but unwilling
> > > > to help rectify the problem.
> > > 
> > > Well, bsd.stage.mk isn't well commented either. I think right now
> > > only the person who implemented it could write reasonable
> > > documentation.
> > > 
> > > >  If you only want to complain, I think you've made your
> > > > point (a point that everyone is already aware of).
> > > > 
> > > > FYI, I have no dog in the hunt other than I believe stage is a
> > > > welcome update to ports.
> > > 
> > > 1. Implementation
> > > 2. Testing
> > > 3. Documentation
> > > 4. Mandatory
> > > 
> > > We're in stage 2 and it's already mandatory. I'm not against
> > > staging, I'm against making things prematurely mandatory.
> > 
> > With that kind of reasoning we get the ports tree we have now.
> > Meaning a pile of inconsistent, inefficient things, and things like
> > UNIQUENAME not being UNIQUE etc.
> > 
> > the stage work is a 3 years work almost, that has been half
> > abandonned, a lot of time.
> > 
> > Documentation on how to convert has been done on the wiki before
> > making staging mandatory and completed since.
> > 
> > Documentation for the handbook is another beast because the whole
> > handbook as to be touched and reviewed, and I ask a couple of time to
> > people to help me documenting on the handbook.
> > 
> > I don't buy the opinion that the handbook is totally outdated, all
> > the features I added but stage are in the handbook including shebang
> > fix ! so perhaps that can be improved but that is there.
> > 
> > Before committing the stage support I made sure that all previous
> > things has been documented.
> > 
> > and sorry but my priority is to have the ports tree back into a sane
> > state where we have consistency and sane packages, do documentation
> > has much as I can and I try to avoid having too much latency for
> > documentation.
> > 
> > Bapt
> 
> I agree for the most part, the only suggestion I'd make is to reference
> undocumented features in the Porter's Handbook and link to their Wiki
> pages - that should be a matter of minutes and would make sure that
> people starting from the handbook get the complete picture.
> It's really hard for newcomers not following ports@ to find this bit of
> information otherwise, especially since the Wiki is not that well
> organized (staging is not even on the Wiki's frontpage). E.g.
> 
> Section X: Staging
> Staging is mandatory for new ports, it's not documented in here yet,
> but details can be found in the FreeBSD wiki (link to staging support
> page).
> 

I do buy this argument :) and I'll see want I can do for that in the next couple
of days.

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