[Grok-dev] Re: initial thoughts on grokproject

Philipp von Weitershausen philipp at weitershausen.de
Wed Feb 28 11:11:27 EST 2007

Martijn Faassen wrote:
> Philipp von Weitershausen wrote:
> [snip]
>> In addition to that, the project template should also include a 
>> top-level README.txt that explains where you can put your code and how 
>> to start Zope, etc. I think you're suggesting that as well..
> I'd also suggest we *take away* the README.txt inside the grok project 
> itself. It's a bit misleading after the latest changes, and we can't 
> seriously expect people who read absolutely no documentation to really 
> know what to do, even *with* the README.txt.
>> By the way, after trying out different package/repository layouts, I 
>> find I don't like 'src' a lot. I'm thinking of getting rid of it...
> What would you suggest is used instead? If you put the package name 
> immediately under the project, you gain:
> * a directory structure that's a bit flatter
> You lose:
> * predictability about where the source code is. If you say 'src', it's 
> immediately obvious for people where to go look for the code.

Perhaps it makes things obvious in the first moment. However, after that 
I think it just gets annoying.

> * if you put the project on the PYTHONPATH, anything in the project 
> directory is put in the PYTHONPATH, instead of just the package we want 
> to put there. I'm not sure whether this happens with (develop) eggs.

I'm not sure either. Is that really a problem?

>>> 2) "grokproject asks for a module, a demo module, what is that about?".
>>> I thought it wasn't that important so I just pressed enter, but it did
>>> really want something. If it's just for giving an example, maybe it can
>>> just be called demo.py and don't necessarily ask about it? To me it's a
>>> non-obvious question that gets in my way to get started.
>> Yes, I agree. Perhaps it can indeed be made optional. If no name was 
>> supplied, no file is created.
> Creating no file at all seems wrong to me. You end up with a 
> non-functional grok application! I think a file *should* be created, but
> perhaps just with a standard name such as 'app.py'.

Yeah, you're right. app.py as a default seems good to me.

>>> 3) "I'm asked for a password, but will it be encrypted or not?"
>>> mkzopeinstance asks if you want to use SHA, plain text or some other
>>> hashing stuff. Does grok use plain as default? Can you change that? To
>>> me it would make sense if grokproject asked for this, but maybe it's
>>> because I'm used to mkzopeinstance asking me that.
>> I'm all for
>> a) improving the documentation on this issue (where is the password 
>> stored and how do I change it?)
>> b) supporting encryption
>> Note that b) requires a Zope 3 instance recipe that supports 
>> encryption, e.g. gocept.zope3instance.
> I think it'd be good to switch to gocept.zope3instance for other 
> reasons, as the startup script could be placed under bin/ directory in 
> the project. That way we don't need to point people to 'parts' anymore 
> at all.

Yep (see below).

>>> 4) "Now I have my project. But what are these directories about? Do I
>>> need to run bootstrap/bootstrap.py? Do I need to know about eggs to get
>>> going? Do I need to create them? How do I start the server and see the
>>> result of my work?"
>>> I think it would be great with a README.txt in the project root folder
>>> that explains what is inside each toplevel folder. It should explain
>>> what bin/test and bin/buildout does. It should explain what bootstrap
>>> folder is about, how you use buildout.cfg and setup.py, what is inside
>>> parts. "parts" is a weird name btw :)
>> +1
> I don't think grokproject should be in charge of creating documentation. 
> I think it should create a README.txt that gives a few basic hints and 
> points to the real documentation on the web.

That would work for me too.

>>> I think bin/ should include runzope, zopectl and zpasswd.
>> +1 This would be something the Zope 3 instance recipe should take care 
>> of. gocept.zope3instance supports this, I believe. 
>> gocept.zope3instance has other problems, IMO, in that it doesn't (or 
>> at least didn't when I looked at it) the creation of ZCML slugs 
>> through buildout.cfg.
> Christian, comments?
> One comment on grokproject that I have is that grokproject doesn't seem 
> to update itself when I use 'easy_install -U grokproject'. Perhaps this 
> is because it's being pulled from SVN.

It's apparently because it's pulled from SVN HEAD and not a specific 
revision. That way it can't tell whether it's got the newest one or not.

> This means that if I install 
> grokproject once I'm stuck with that version forever, unless I go to my 
> /usr/lib/site-packages and wipe out the egg manually. That's not good. 
> How to fix that?

I think adding a setup.cfg with

tag_build = dev
tag_svn_revision = true

and then reregistering it with the Cheeseshop should register 
grokproject as version 0.1dev-rN. Then later after some changes, we 
register it again as version 0.1dev-r(N+n) (the revisions are 
automatically picked up from the svn checkout). That way easy_install 
will think it's a new version AFAIK.

I'll try that later.

http://worldcookery.com -- Professional Zope documentation and training
Next Zope 3 training at Camp5: http://trizpug.org/boot-camp/camp5

More information about the Grok-dev mailing list