[Framework-Team] comments about the plone style guide

[johannes raggam]

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

I cannot find the conventions.rst file in buildout.coredev, so i
discuss some thoughts on the Plone style guide here.

I refer to the blueprint:
https://github.com/plone/plone.api/blob/master/docs/contribute/conventions.rst


On imports
- ----------

This is a matter of taste, but I'd prefer to have 3 groups and sort
those 3 blocks individually.

- - Group 1: imports without from
- - Group 2: imports with from
- - Group 3: imports from the current module's package

so, e.g. for plone.api:

    import random
    import transaction

    from App.config import getConfiguration
    from plone.uuid.interfaces import IUUID
    from Products.Archetypes.interfaces.base import IBaseObject

    from plone.api import portal
    from plone.api.exc import InvalidParameterError


Actually, I'm not totally sure about my suggestion, because the import
blocks in plone.api look quite nice.


On docs/HISTORY.txt vs CHANGES.txt
- ----------------------------------

I'd actually prefer CHANGES.rst - the extension .rst for better syntax
highlighting (we have those files in ReST anyways) and CHANGES in the
package's top level directory, because we actually document changes
between releases and have not an historic essay. It just names the
purpose better, I'd say. I'm a non-native English speaker, so I might
be wrong.
docs/HISTORY.rst would be good for very long CHANGES.rst files, where
we might want just to have the changes since the last major version
release in.

Then, we could also be more verbose about how to document changes.

1) Newer changes on top, not bottom of a release-block.
2) Like so (note also the versioning scheme):

"""
Changelog
=========

1.0dev (unreleased)
- -------------------

- - Document you change.
  [github_userid_1]

- - Older change.
  [github_userid_2]


1.0a1 (2012-12-12)
- ------------------

"""


Prefer .rst over .txt for any documentation, even doctests
- ----------------------------------------------------------

Just because of the nice syntax highlighting.


- -- 
programmatic  web development
di(fh) johannes raggam / thet
python plone zope development
mail: office at programmatic.pro
web:  http://programmatic.pro
      http://bluedynamics.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with undefined - http://www.enigmail.net/

iEYEARECAAYFAlDHqMwACgkQW4mNMQxDgAdmuwCbBzErCxxnONJv/cvZiP2qUDAE
dT8AoLsWuCZujaAyWrAz3I7m1fb6bdpu
=DCph
-----END PGP SIGNATURE-----