[Framework-Team] comments about the plone style guide

[johannes raggam]

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

i'm going to open the pull-req on plone.api for this, as discussed in
the meeting.
sorry for the noise.

On 12/11/2012 10:42 PM, johannes raggam wrote:
> 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.
> 
> 
> _______________________________________________ Framework-Team
> mailing list Framework-Team at lists.plone.org 
> https://lists.plone.org/mailman/listinfo/plone-framework-team
> 

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

iEYEARECAAYFAlDHqZYACgkQW4mNMQxDgAe5MACgz7YCWrre0JheP07rB7LUOqDY
ksYAnRj8GCldpQpMobZwec+YEk5vrmBx
=oTl2
-----END PGP SIGNATURE-----