[Grok-dev] Re: initial thoughts on grokproject

[Martijn Faassen]

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.

* 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.

>> 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'.

>> 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.

>> 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.

>> 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. 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?

Regards,

Martijn