[Zope-dev] pinning, nailing and kgs'ing

[Kevin Teague]

I wanted to try using the snowsprint-viewlets2 branch of grok in my  
project the other day. It took me a little time to figure out how to  
do this, so I thought it'd be nice if there was a bit of documentation  
on how-to pull in a development version of Grok into a grok project,  
so I wrote this:

http://grok.zope.org/documentation/how-to/trail-blazing

(I've configured the Grok site to allow OpenId for authentication, and  
granted the View and Reply to Item permissions to documentation that  
is in the "Waiting for Review" state, which means you need to log-in  
to see the document, but that anyone can log-in, which seems like a  
decent compromise for unreviewed documentation on the Grok site which  
is potentially incorrect.)

The part where I was fuzzy in the documentation process was the  
terminology for Known Good Sets. There are Grok releases such as "Grok  
0.11" which has been called "pinned versions" (or "nailed versions")  
and when writting my help doc I've been calling this a "Known Good  
Set". I would propose this definition for Known Good Set:

   Known Good Set : A frozen set of Python egg names and version  
numbers that have been tested to work together. This set of eggs is  
also available from an archive maintained by the publisher of the  
known good set.

For Grok this would be:

http://grok.zope.org/releaseinfo/grok-0.11.cfg

and the eggs are archived at:

http://download.zope.org/distribution/

(at least that's my understanding of the Grok releases, maybe I don't  
have that quite right ... )

However, the Zope 3.4 release announcement varies a bit from my  
understanding of Grok-centric understanding of Known Good Set:

"The known good set -- or in short KGS -- is a package index that  
derives from the official Python Package Index (PyPI) and thus  
contains all available packages in the Python world. But for a  
controlled set of packages, only certain versions that are known to  
work together are available. "

This is the part that seems a bit confusing to me, since it's not  
clear if the "set" also includes the super-set of packages from PyPI.  
It's also not clear if the super-set of all PyPI packages is also a  
continually updated mirror, or a frozen index. Or is the known good  
set just the controlled set of packages? It's also not entirely clear  
on how maintenance releases happen with Zope 3.4 from this, e.g. one  
could interpret the contents of the versions.cfg URL as either  
"frozen" (Zope 3.4.0-final) or "latest". For maintenance releases  
would there be:

http://download.zope.org/zope3.4/versions.cfg
http://download.zope.org/zope3.4.1/versions.cfg
http://download.zope.org/zope3.4.2/versions.cfg

Or if this URL will always contain the latest stable packages in the  
3.4 series then perhaps this should be more explicit with an URL such  
as:

http://download.zope.org/zope3.4/current-versions.cfg

Shouldn't there also be URLs such as these?

http://download.zope.org/zope3.4/3.4.0c1-versions.cfg
http://download.zope.org/zope3.4/3.4.0-versions.cfg
http://download.zope.org/zope3.4/3.4.1-versions.cfg

It should also be more explicit what "controlled" means. It seems like  
this is the same set of packages and versions and versions.cfg except  
that it also contains versions of previous packages? Is this a  
continually updated set of the most current versions of all packages  
that make up the Zope 3.4 series after all test suites pass?

http://download.zope.org/zope3.4/controlled-packages.cfg

Too me it seems easier to understand if there are two URLs in  
buildout's find-links setting. e.g. for Plone there is a link to a  
controlled archive of Plone produced packages, then there is a link to  
PyPI (well the PPIX mirror actually), which makes it more obvious that  
there is a Zope managed archive of packages, and then there is the  
wide, wooly world of all Python packages:

find-links =
     http://dist.plone.org
     http://download.zope.org/ppix/

Anyways, I hope I don't sound too complain-y, but it would be much  
appreciated if the terminology and plan for maintaining the Zope 3.4  
release series was made a bit clearer. And it would also be really  
nice if the Grok terminology and release methods lined up with the  
Zope 3 terminology and release methods :)