­­=================================
ZopeSkel Sprint 2008 User Stories
=================================

Atschema needs validators
-------------------------
The atschema local command for the archetype template doesn't handle validators.


When you create a new schema field, there's no question about validators. Also,
when you pick something like "integer" for your field type, for reasons beyond
my comprehension, the integerField class doesn't validate user input. You'd
think, with it being an integer field, that it would prevent you from putting in
a string. It doesn't, in fact, it breaks with an error. Nice.


Generated Python Code Needs to Be Cleaned Up
--------------------------------------------
The python code generated by zopeskel templates needs to be consistent and
preferably follow PEP8

See: http://www.fantascienza.net/leonardo/ar/python_best_practices.html

and: http://www.python.org/dev/peps/pep-0008/


ZCML Needs to be Cleaned Up
---------------------------
ZCML generated by zopeskel needs to be consistent and follow the ZCML style
guide

See: http://wiki.zope.org/zope3/ZCMLStyleGuide


Documentation: We need better user feedback during interactive sessions
-----------------------------------------------------------------------
Paster works by asking the user a bunch of questions. Those questions aren't
always very helpful if you've never done plone or zope stuff before. I'd like to
see them cleaned up.

Documentation: ZopeSkel needs better plone.org docs!
----------------------------------------------------
ZopeSkel is woefully represented on the plone.org site. This shouldn't be, since
it's such a hugely useful tool.


zope.formlib support
--------------------
We need to be able to create zope.formlib browser views


CMFFormContoller Support
------------------------
We need to be able to create the .cpy, .cpt, and .metadata files you need when
building a CMFFormController form.


Namespace Specification for Eggs
--------------------------------
If you create an egg, you have to make sure that the foldername and the
namespace + package names match up. e.g. "paster create -t plone my.package"
means you *have* to say namespace = "my" and package = "package".

From Martin Aspeli's post, http://plone.org/support/forums/core#nabble-td348745

I'd like to suggest that since the folder name and the package/namespace have to
be the same, that we take one argument and parse that to get the namespace
pieces. Need to check if this makes sense from a pure egg standpoint.


Alternate Inputs for True/False
-------------------------------
Typing "True" and "False" sucks. We need to ensure we can accept t, f, T, F, y,
n, Y N etc.

From Martin Aspeli's post: http://plone.org/support/forums/core#nabble-td348745


Archetype Product Tests
-----------------------
You always get a tests.py, and sometimes you get a tests/ package as well. One
will beat the other. tests.py is also a bit limited for most purposes. (this
refers to the paster create "archetype" template)

See: http://plone.org/support/forums/core#nabble-td348745


Archetype Content Type Tests
----------------------------
The paster addcontent template for content types doesn't add any tests. I think
some very basic boilerplate tests (even if they fail because the content isn't
globally addable) illustrating how to test a content type would be great


How Do You Test ZopeSkel?
-------------------------
There needs to be some R&D done to see how we can go about testing ZopeSkel and
the code it generates. Specifically, I'd like to see a test for the buildout and
archetype templates that verifies that the code generated works. Also, I'd like
to see tests for the different possible combinations of input for the atschema
local command. I think part of this means switching the option parser so that it
can take command line arguments to automatically answer questions.

jjmojojjmojo: I looked into using the --config command line option, and I realized
that it's not available in the base local command :(


plone Template Needs Localcommands
----------------------------------
The plain plone paster create template doesn't put in hooks so you can later use
addcontent.


Buildout Options
----------------
plone3_buildout - discuss feasibility of local commands for adding instances and
products (Suggestion from MatthewWilkes but can't commit time :()

Matthew suggested that we talk about what can be done to make mundane/unclear
tasks related to changing buildout.cfg. Specifically, adding non-egg products
and multiple instances. He mentioned that evilbungle wrote some ZopeSkel code
(not committed yet) to add instances to buildout.cfg.



Display Available Local Commands When Available
-----------------------------------------------
From Joel Burton - it'd be great if the user could be alerted when a template that
just completed running could give the user a note about the local commands that
are made available by the template.

Get Rid of -t
-------------
From Joel Burton - the -t necessary when calling paster create is confusing.

This is a paste script thing, but might be worth looking into to simplify
ZopeSkel.

Windows issues with Python in a path containing spaces
------------------------------------------------------
Issue 9 from the ZopeSkel issue tracker: http://plone.org/products/zopeskel/issues/9
A workaround has been uploaded as attachment 3 below (copies bootstrap.py from
zc.buildout trunk).  A more robust solution is still being investigated.

Plus, zc.buildout also has problems in the same environment (patch for this issue
as attachment 1 below; applies to zc.buildout trunk).
Suggested commit message:
Removed _safe_arg and updated spawn* calls to subprocess.Popen.
Refactored much of the jython support code to its own module.

Jason R. Coombs (jaraco/jaraco_mobile) is working on patches.



JJ's atschema Changes Break Tests
---------------------------------
Currently the tests (executed by running python setup.py test in the main zopeskel egg)
fail due to problems with atschema.

jjmojojjmojo: This is due to at least two problems with atschema:
- I moved some stuff around in the archetypes template
- I have a bunch of print statements in __init__() inside the template

I'm working on this but will probably table it. It's really hard to find a
good place to put the notice that atschema prints to the user, and I'll fix the
tests that look for file layouts all at once.

The addcontent command doesn't support the --config parameter
-------------------------------------------------------------
paster create offers a --config command. It allows you to save the answers to the questions
as a config file. paster addcontent doesn't support this, and it should.

Team

• Josh Johnson (josh under johnson at unc dot edu )
• Clayton Parker [claytron] (clayton at sixfeetup dot com)
  
• Ian Bicking - I probably won't be attending this sprint, but I'll be at the sprints, and I'm happy to help with PasteScript stuff, or expedite any patches you have to PasteScript (call me over and I can review and commit a change you've made on the spot)
• Mark van Lent [markl] (mark at zestsoftware dot nl) 
• Jason R. Coombs (jaraco at jaraco dot com) 
• Emanuel Sartor (emanuel at menttes dot com) 
• Alan Hoey [evilbungle] (alan dot hoey at teamrubber dot com)
  

Communications ­

I've registered #zopeskel on irc.freenode.net. Please join us there for planning prior to the sprint and communications during the sprint.

ZopeSkel Archetypes HOWTO

Here's a quick overview if the things I've been using ZopeSkel for, and a general "how does it work" sort of thing. It's made my life a lot easier :)

Unix (Ubuntu, but should port)

========================================
ZOPESKEL + ARCHETYPES - BUIDLD A DEV ENV
========================================

Dev Environment (Ubunutu)
-------------------------
$ sudo aptitude install build-essential python-dev python2.4 python2.4-dev subversion

Easy Install (setuptools)
-------------------------
$ cd /tmp
$ wget http://pypi.python.org/packages/2.4/s/setuptools/setuptools-0.6c9-py2.4.egg#md5=260a2be2e5388d66bdaee06abec6342a
$ sudo sh setuptools-0.6c9-py2.4.egg

(This is different than the way I used to do it, via ez_setup.py. see http://pypi.python.org/pypi/setuptools/)

ZopeSkel
--------
$ sudo easy_install -U ZopeSkel
- or -
[ from JJ's zopeskel branch ]
$ cd ~
$ svn co http://svn.plone.org/svn/collective/ZopeSkel/branches/jjmojojjmojo-AT/
$ cd jjmojojjmojo-AT
$ sudo python2.4 setup.py develop

Check for ZopeSkel
------------------
$ paster create --list-templates
Available templates:
  archetype:          A Plone project that uses Archetypes
  basic_namespace:    A project with a namespace package
  basic_package:      A basic setuptools-enabled package
  basic_zope:         A Zope project
  kss_plugin:         A KSS plugin template
  nested_namespace:   A project with two nested namespaces.
  paste_deploy:       A web application deployed through paste.deploy
  plone:              A Plone project
  plone2.5_buildout:  A buildout for Plone 2.5 projects
  plone2.5_theme:     A Theme for Plone 2.5
  plone2_theme:       A Theme Product for Plone 2.1 & Plone 2.5
  plone3_buildout:    A buildout for Plone 3 projects
  plone3_portlet:     A Plone 3 portlet
  plone3_theme:       A Theme for Plone 3.0
  plone_app:          A Plone App project
  plone_hosting:      Plone hosting: buildout with ZEO and any Plone version
  plone_pas:          A Plone PAS project
  recipe:             A recipe project for zc.buildout
  silva_buildout:     A buildout for Silva projects

Buildout Skeleton
-----------------
$ paster create -t plone3_buildout mybuildout
Selected and implied templates:
  ZopeSkel#plone3_buildout  A buildout for Plone 3 projects

Variables:
  egg:      mybuildout
  package:  mybuildout
  project:  mybuildout
Enter zope2_install (Path to Zope 2 installation; leave blank to fetch one) ['']:
Enter plone_products_install (Path to directory containing Plone products; leave blank to fetch one) ['']:
Enter zope_user (Zope root admin user) ['admin']:
Enter zope_password (Zope root admin password) ['']: admin
Enter http_port (HTTP port) [8080]:
Enter debug_mode (Should debug mode be "on" or "off"?) ['off']: on
Enter verbose_security (Should verbose security be "on" or "off"?) ['off']: on

Archetypes Product
------------------
$ cd mybuildout/src
$ paster create -t archetype my.product
Selected and implied templates:
  ZopeSkel#basic_namespace  A project with a namespace package
  ZopeSkel#plone            A Plone project
  ZopeSkel#archetype        A Plone project that uses Archetypes

Variables:
  egg:      my.product
  package:  myproduct
  project:  my.product
Enter title (The title of the project) ['Plone Example']: My Product
Enter namespace_package (Namespace package (like plone)) ['plone']: my
Enter package (The package contained namespace package (like example)) ['example']: product
Enter zope2product (Are you creating a Zope 2 Product?) [True]:
Enter version (Version) ['1.0']:
Enter description (One-line description of the package) ['']:
Enter long_description (Multi-line description (in reST)) ['']:
Enter author (Author name) ['Plone Foundation']:

Enter author_email (Author email) ['plone-developers@lists.sourceforge.net']:
Enter keywords (Space-separated keywords/tags) ['']:
Enter url (URL of homepage) ['http://svn.plone.org/svn/plone/plone.example']:
Enter license_name (License name) ['GPL']:
Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:

Wire Up Product To Plone
------------------------
$ cd ../
$ vi buildout.cfg

Make changes:
[buildout]
...
develop =
    *src/my.product*
...
[instance]
eggs =
    ${buildout:eggs}
    ${plone:eggs}
    *my.product*
...
zcml =
    my.product

Save and exit.

Check for Local Commands
------------------------
$ cd src/my.product
$ paster help
Usage: paster [paster_options] COMMAND [command_options]

Options:
  --version         show program's version number and exit
  --plugin=PLUGINS  Add a plugin to the list of commands (plugins are Egg
                    specs; will also require() the Egg)
  -h, --help        Show this help message

Commands:
  create       Create the file layout for a Python distribution
  help         Display help
  make-config  Install a package and create a fresh config file/directory
  points       Show information about entry points
  post         Run a request for the described application
  request      Run a request for the described application
  serve        Serve the described application
  setup-app    Setup an application, given a config file

ZopeSkel local commands:
  addcontent   Adds plone content types to your project

$ paster addcontent --list
Available templates:
    atschema:     A handy AT schema builder
    contenttype:  A content type skeleton
    portlet:      A Plone 3 portlet
    view:         A browser view skeleton
    zcmlmeta:     A ZCML meta directive skeleton


Content Type(s)
---------------

Container
~~~~~~~~~
$ paster addcontent contenttype
Enter contenttype_name (Content type name ) ['Example Type']: Date Book
Enter contenttype_description (Content type description ) ['Description of the Example Type']: A Simple Date Book
Enter folderish (True/False: Content type is Folderish ) [False]: True
Enter global_allow (True/False: Globally addable ) [True]:
Enter allow_discussion (True/False: Allow discussion ) [False]:

Non-Container
~~~~~~~~~~~~~
$ paster addcontent contenttype
Enter contenttype_name (Content type name ) ['Example Type']: Entry
Enter contenttype_description (Content type description ) ['Description of the Example Type']: A Date Book Entry
Enter folderish (True/False: Content type is Folderish ) [False]:
Enter global_allow (True/False: Globally addable ) [True]: False
Enter allow_discussion (True/False: Allow discussion ) [False]:

- repeat for each content type in your system -

Archetypes Schema
-----------------
$ paster addcontent atschema
Welcome to the ATSchema Builder. Field names/widgets can be specified in lowercase or upper case.
NOTE: No need to add 'widget' or 'field' to the names. atschema does the work for you!
See
    http://plone.org/documentation/manual/archetypes-developer-manual/fields/fields-reference/

and
    http://plone.org/documentation/manual/archetypes-developer-manual/fields/widgets-reference
for field and widget details
Enter content_class_filename (What is the module (file)name of your content class?) ['exampletype']: datebook
Enter field_name (What would you like to name this field?) ['newfield']: year
Enter field_type (What kind of field should I make for you?
Some examples: [boolean,computed,cmfobject,datetime,file,fixedpoint,float,image,integer,lines,reference,string,text]) ['string']: integer
Enter widget_type (What kind of widget do you want to use?) ['default']:
Enter field_label (What should be the label of this field (title)?) ['New Field']: Date Book Year
Enter field_desc (What should be the description of this field (help text)?) ['Field description']: Limit this date book to one specific year
Enter required (Is this field required?) ['False']:
Enter default (If you'd like a default type it here, otherwise leave it blank) ['']:

- repeat for each field in your schema -

Bootstrap/Buildout
------------------
$ cd ../../
$ python2.4 bootstrap.py
$ ./bin/buildout

Start Zope
----------
$ ./bin/instance fg

Eyeball Test
------------
1. Open http://localhost:8080 in a browser. You should see the Zope welcome page
2. Click the Zope Management Interface link, enter admin/admin for username/password
3. Select "Plone Site" from the dropdown on the right.
4. Enter a useful id (plone). The rest of the fields don't matter right now.
5. Click "Add Plone Site" button
6. Watch console for any errors during plone site setup
7. Click on the link to "plone (Site)"
8. Click on "portal_quickinstaller"
9. Check the box next to "My Product"
10. Click "Install"
11. Watch the console for errors
12. You should see "My Product" under "Installed Products"
13. Open http://localhost:8080/plone (it usually takes some time to load first time round)
14. Click the "Add New" link.

15. Look for Date Book in the list
16. Click on Date Book in the list
17. Fill out the form. We'll use "My Date Book" for the title, "A Date Book" for the description, and 2008 for the year
18. Click save button

­