[Zope-dev] [Zope-Checkins] SVN: Zope/branches/tseaver-clarify_install_docs/doc/ Split out docs for 'normal' installation from those using 'zc.buildout'.

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

yuppie wrote:

> Tres Seaver wrote:
>> Chris Withers wrote:
>>> By all means, document virtualenv as an option, but blessing it as "the
>>> one true way" is a bit much...
> 
> I'm also surprised that you propose to make this *the* recommended way.
> 
>> Here's my rationale:
>>
>> - - The docs are intended primarily for folks who want to install and
>>    run Zope, rather than hack on it.
> 
> So you recommend virtualenv for administrators and buildout for 
> developers? Or where do you draw the line? And when do you recommend to 
> switch from one setup to the other? Or do you always recommend virtualenv?

I recommend virtualenv to anybody who just wants to install and run the
Zope2 appserver, without needing to drink a lot of "kool-aid":  just
install it from PyPI, run 'mkzopeinstance', and you're done.  Note that
I specifically remomve the non-virtualenv easy_install docs:  I don't
want us *ever* to encourage the use of easy_install outside a virtualenv.

> I thought zc.buildout is preferred by most people in the Zope community.

buildout works for *developers*:  it is completely strange for people
who just want to install and run Zope.  Mixing the buildout version of
the installation in with the non-buildout version was a disaster, from a
readability standpoint.


>> - - zc.buildout is *super* heavyweight compared to virtualenv
>>
>> - - zc.buildout creates an environment which is puzzling as hell for
>>    anybody who hasn't already drunk the koolaid ('parts'?  'eggs'?
>>    WTF?)
> 
> virtualenv is also puzzling if you are not familiar with it. Using 
> activate and deactivate or the right paths isn't much easier to learn 
> than using zc.buildout.

The environment itself is much closer to what people expect:  libraries
installed under 'lib/pythonX.Y', scripts in 'bin', headers in 'include',
no funky 'parts' or 'eggs' directories, no idea that config files might
get blown away just because you update software.  I know that some of
that is due to popular recipes, but that argument is specious:
buildout's value proposition derives in part from the network effect of
having those recipes available and widely used.

Activate is a completely unnecessary attractive nuisacne:  I *never* use
it, and I routinely see people who *do* use it end up running from
different environments than the ones they think they are running.

>> - - virtualenv, or something damn near it, is likely to land in Python
>>    itself.
>>
>> - - Nearly anybody else in the Python world is more likely to be
>>    familiar with the virtualenv stuff than with buildout.
> 
> But not everybody in the Python world is familiar with virtualenv. Why 
> should we encourage people to make themselves familiar with virtualenv 
> instead of zc.buildout?

I would bet that, outside the Zope community, virtualenv's mindshare is
ten times that of buildout.  Adding it to the stdlib was actually a
topic on the agenda of the pre-PyCon language summit, for instance.

>> - - We have two alternate zc.buildout scenarios (install Zope + run
>>    mkzopeinstance vs. self-contained environment).  The first has no
>>    real advantage over the virtualenv one, except being able to
>>    run buildout to update the software (heaven help you if you forget
>>    to configure the index properly!).  The second leaves you without
>>    the annotated config file, a *major* faux pas.
> 
> I consider the self-contained scenario still as experimental. Following 
> the instructions requires much more typing than the other scenarios. But 
> I'm optimistic it can and will be improved.

The self-contained mode is likely *perfect* for developers who produce a
highly-customized bundle o Zope, 3rd party software, and custom code.
It just isn't right as the "first choice" for somebody installing Zope
for the first time.


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkuOxiAACgkQ+gerLs4ltQ4UhwCgyb5BGFZD1Lz/9rYLng10ekx8
sk4An2pmynQ8PUZagq1CAbd6+tasXyIj
=B00w
-----END PGP SIGNATURE-----