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

[Alexander Leidinger]

Hi,

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.

Bye,
Alexander.

-- 
              The best things in life are free, but the
                expensive ones are still worth a look.

http://www.Leidinger.net                       Alexander @ Leidinger.net
  GPG fingerprint = C518 BC70 E67F 143F BE91  3365 79E2 9C60 B006 3FE7
-------------- next part --------------
Install-time vs. commit-time plist
----------------------------------


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.




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. 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. 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.

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).

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.

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.