[pmwiki-users] Numberin in Cookbook files

[Patrick R. Michaud]

On Sat, Aug 26, 2006 at 01:43:09AM +0200, Clemens Gruber wrote:
> 
> >to download. I renamed the previous version to stylepage1.php.
> 
> Hi, this leads me to another question:
> 
> How should I (or should I) label versions in 
> http://www.pmwiki.org/wiki/Cookbook/ ?

I prefer to use dates to indicate the version of recipes, as
opposed to simple numbers.  In particular, it means I can compare
the timestamps of the files I have against the date in the gray box
to know if a new version is available, it also helps people to
instantly know how recently a recipe has been modified.

On the other hand, I know very well the satisfaction that comes
from achieving a "1.0" or "2.0" milestone, and the fact that
dates as version numbers don't always communicate the degree of
change from one version to the next.  (This is why PmWiki uses
2.1.x instead of dates as its numbering scheme.)  So, it's perfectly
acceptable to me for people to use a different versioning scheme
in the Cookbook.  However, it might be nice if the "Version:"
line in the headers included a date, as in "Version: 1.0 (2006-08-25)".

(And if including a date, it's really nice if it's ISO-formatted,
as in "2006-08-25" or "20060825".)

> Some specify numbers in the head (grey box). This is good to know what's 
> the up to date version. But so you have no cance to compare new features 
> with old code or get code without feature x. Is it wished to have older 
> versions available? So I have to use cokbook_v0.1.php, cokbook_v0.2.php, 
> or should ther be only one version without version number in the file name?

A recipe author can do something similar to what PmWiki does for 
its distributions, which is to have both numbered or dated copies 
(pmwiki-2.1.15.zip) and a copy which is always the latest released
version (pmwiki-latest.zip).

For example, suppose I have a "chickensoup.php" recipe I'm 
maintaining in the cookbook.  If I think it's important for older 
versions to remain available, then every time there is an update to
my recipe I would upload two copies to the Cookbook, an unversioned 
copy named "chickensoup.php", and another copy that includes a
version number, like "cookbook-yyyymmdd.php".  This gives administrators
the ability to quickly find and use the latest version, while also
preserving the ability to recover older ones, all without too
much effort on the part of the maintainer (i.e., the price of
uploading the file twice).

Again, these are just ideas and suggestions of a good set of
guidelines to follow; but recipe writers are free to follow
whatever conventions they wish.  I figure that if someone
takes the time to contribute their work to the community,
they get a very strong say in how it is presented.  :-)

Thanks for the excellent question,

Pm