[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:
>> 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 :)
> 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