[Framework-Team] comments about the plone style guide

Marcio Mazza marciomazza at gmail.com
Wed Dec 12 12:30:35 UTC 2012


I made a comment about import order there:
https://github.com/plone/plone.api/commit/c516d5f7d427c239b3098a7c73f0e1b6c43e2756#L0R45


On Tue, Dec 11, 2012 at 7:45 PM, johannes raggam <raggam-nl at adm.at> wrote:

> -----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-----
> _______________________________________________
> Framework-Team mailing list
> Framework-Team at lists.plone.org
> https://lists.plone.org/mailman/listinfo/plone-framework-team
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.plone.org/pipermail/plone-framework-team/attachments/20121212/a8c2a5c9/attachment.html>


More information about the Framework-Team mailing list