Proposal for an additional (sub)section in the porters handbook

[Alexander Leidinger]

Adam Weinberger <adamw at FreeBSD.org> wrote:

> Alexander Leidinger wrote:
>> based upon the consensus (of the absolute majority of participants
>> which consisted of a lot of committers and some users) in the discussion
>> which starts with
>> http://lists.freebsd.org/pipermail/freebsd-ports/2005-January/019974.html,
>> I wrote the attached proposal for the porters handbook.
>>
>> Comments please.
>
> This is political rhetoric, not a collection of helpful suggestions. 
> You have too much "thou shalt not" in there, and it looks more like a 
> collection of arguments for removing the plist generating code from 
> bsd.port.mk.

I think we don't talk about the same thing. See below.

>> ------------------------------------------------------------------------
>>
>> Install-time vs. commit-time plist
>
> These are not phrases that porters use. The PH is not the place to 
> introduce personal monikers.

So far the handbook doesn't differentiate between them. Since I can't talk
about some behaviour without naming it, I had to come up with a name. Since
I didn't used those terms in the thread I referenced in my previous mail (I
used static and dynamic for commit-time and install-time instead), there was
some kind of misunderstanding there. I tried to make it unambiguous this
time.

>> ----------------------------------
>>
>>
>> Definition "static plist": a static plist is a plist which does not 
>> contain <ref "7.1 Changing pkg-plist based on make variables">plist 
>> variables</ref>.
>>
>> Definition "dynamic plist": a dynamic plist is a plist which 
>> contains <ref "7.1 Changing pkg-plist based on make variables">plist 
>> variables</ref>.
>>
>> Definition "install-time plist": an install-time plist is a plist 
>> which is automatically generated at the time a port is installed.
>>
>> Definition "commit-time plist": a commit-time plist is a plist which 
>> is included in the CVS reposirory (either as a seperate file or as 
>> PLIST_FILES and PLIST_DIRS variables in the Makefile of the port). 
>> It may be a static or a dynamic plist. It may also be manually 
>> written or automatically generated.
>
> These names make no sense to me whatsoever. Either a plist is 
> automatically generated or it isn't. First of all, nobody should be

It can be automatically generated at install-time, or it can be automatically
generated by a makefile target or a tool before the plist is committet. I
don't object to automatically generated plists, as long as they are
available as a pkg-plist file in CVS or embedded into the Makefile as
PLIST_{FILES,DIRS}.

That's the point I try to make with this proposal.

> discouraged from using variables in the plist. In fact, the PH says 
> that people SHOULD use variables, e.g. %%DATADIR%%, etc. So, I would

I don't want to discourage the use of variables (I use them myself). It was
pointed out to me that I may have mixed static and dynamic in one case. I
didn't took the time to look at the corrected version yet. So this may be
the case for this miscommunication of my intentions.

> advise not differentiating between your "static plist" and your 
> "dynamic plist."

I try to come up with a text which avoids this.

> What you call an "install-time" plist is what the rest of us call a 
> "dynamic plist." And the "commit-time" category makes absolutely no

Some people used the definition I provided for "dynamic plist". See the
thread I referenced in my previous mail.

> sense to me whatsoever. There is no part of a port framework that 
> ISN'T in CVS, so I fail to see what that category will accomplish 
> except to confuse people. It sure has me baffled. If you're going to

Ok, I try to come up with a better description of a commit time plist later.

> add anything to the PH -- and I don't think you should -- you should

Since more and more install-time plists show up in ports and we lose some
features because of this, I think it's necessary.

> narrow it down just to static and dynamic plists, and you should use 
> the typical usage of "dynamic plist".

But it's ambiguous. See the thread I referenced in my previous mail.

>> Some maintainers prefer to use install-time plists. While the use of 
>> them is not forbitten, maintainers have to use commit-time plists 
>> wherever possible.
>
> See, as soon as you use "have to", you've negated any purpose of your 
> addition past political rhetoric. The entire thing could be shortened

Ah! Pav, did you referenced to this as being "political" as well? I thought
you talked about the "benefits"-list. Ok, I will change this.

> down to, "Please use static plists when possible, as it enables users 
> to grep(1) through available plists to discover, for example, which 
> port installs a certain file."
>
>> Exceptions are complex ports where the plist changes a lot based 
>> upon optional features of the port and getting the dynamic plist 
>> right would result in a major headache or ports which change the 
>> plist based upon the version of BUILD_DEPENDS used (e.g. ports which 
>> generate docs with Javadoc).
>
>> Ports where it is possible to use a static commit-time plist have to 
>> use a commit-time plist.
>
> This feels wrong. Nobody *has* to use share/portname in their plist 
> if they choose to use %%DATADIR%%. Using variables cuts down on the 
> amount of bulk in CVS; the GNOME team uses it all the time for things 
> like evolution, where changing one line in the Makefile saves 
> changing hundreds of lines in the plist.

I think this is now obsolete, since I explained above that I don't want to
discurage %%FOO%% variables.

>> Maintainers which prefer install-time plists are encouraged to add a 
>> new target to their port which generates the plist, so that they can 
>> enjoy the benefit of an install-time plist (automatic generation of 
>> the plist) while the benefits of a commit-time plists are preserved.
>
> You seem to be running under the assumption that people only use 
> dynamic plists because they're lazy and don't feel like making a 
> plist themselves.

If you s/dynamic plist/install-time plist/ in the above paragraph: yes, at
least this is the gut of what I've been told by some people which prefer to
use install-time plists instead of commit-time plists.

>> Benefits of commit-time plists:
>>  - Allows to search for files which are not installed. Affects users.
>>  - Allows to determine if a particular port contains what we want. 
>> Affects users.
>>  - Allows to check just with grep if two ports install conflicting 
>> files. Affects users (which debug a problem) and developers (which 
>> process a bug report).
>>  - Allows to check the plist for flaws/pitfalls with portlint. 
>> Affects developers.
>>  - Allows to answer some classes of support requests without the 
>> need to install the port. Affects "support frontliners".
>>  - Allows to notice files which are not build but should be build. 
>> Affects users (quality of the port/package) and developers 
>> (automatic bug notification by the ports build cluster).
>>  - Allows to have a look at the history of what a port installs. 
>> Affects users (which have a problem and need support with an old 
>> version of a port).
>
> About half of those say the exact same thing. Please refer back to 
> the one-sentence example I gave above.

Since Pav suggested that this doesn't needs to be included in the porters
handbook, and I'm fine if this is only mentioned in the commit log, it will
be removed entirely from the text.

>> Drawback of commit-time plists: an install-time plist is generated 
>> when the port is installed while a commit-time plists needs to be 
>> transfered to the user.
>
> In addition to containing a spelling error, that's pretty similar to 
> reminding a user that cats and better than dogs because dogs are 
> dogs. I'm not trying to imply that your arguments are invalid, 
> because they most certainly are valid. My point is that to have them 
> in the PH won't accomplish anything productive.
>
>> Counter argument to the drawback of commit-time plists: while there 
>> are still some locations with limited connectivity where this may 
>> matter, the size of the rest of the ports tree combined with only 
>> transfering differences (if this results in smaller sizes) and 
>> compression (as done by cvsup and portsnap), the additional size of 
>> commit-time plists is negligible.
>
> This sounds like you mulling over an idea in your head. Again, this 
> sort of thing won't benefit anybody by being in the PH. I advise that 
> you just say, "Dynamic plists can be solutions to problems that 
> static plists cannot solve, but please do not abuse them. They exist 
> to make things possible, not to allow you to skip a step of the 
> porting process."

Maybe I wasn't able to communicate the intend (describing the pros and cons)
very good, but your paragraph sounds harsh to me. :-(

Nevertless, I think about your proposal and have a look if it still makes
sense with "s/dynamic/install-time/g; s/static/commit-time/g".

I will post a new version later.

Bye,
Alexander.

-- 
http://www.Leidinger.net  Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org     netchild @ FreeBSD.org  : PGP ID = 72077137
FORTUNE ANSWERS THE TOUGH QUESTIONS: #8

Q:	Is God a myth?
A:	No, He's a mythter.