openstack team mailing list archive

[Andy Smith <andyster@xxxxxxxxx>]

On Thu, Mar 22, 2012 at 9:22 AM, Andrew Bogott <abogott@xxxxxxxxxxxxx>wrote:

>    Just now I set out to merge a recent style guide change from
> python-novaclient into the hacking docs of other OpenStack projects.  My
> patch didn't apply, though, because each project has subtly diverging
> HACKING files.
>
>    Rather than contribute to this divergence, I've now read and compared
> the style guides from Nova, Glance, Keystone, python-keystoneclient, and
> python-novaclient.  From these diffs I've created a file (attached) that
> encompasses the total of all guidelines from all projects.  Remarkably,
> this merge produced only minor disagreements, described below under the
> heading FLAMEBAIT.
>
>    I propose that this unified style guide be copied into each of the
> above projects, with a mandate to maintain consistency henceforth.  Any
> objections?
>
> -Andrew
>
>
> FLAMEBAIT (docstring format):
>
> The only explicit contradiction I came across is regarding docstring
> formatting.  Glance says this:
>
> **DO NOT** leave an extra newline before the closing triple-double-quote.
>
> Nova, this:
>
>  A docstring ends with an empty line before the closing quotations.
>
> I propose that we just pick one or the other, or remove both prescriptions.
>

I'm fine with moving forward to not having the trailing newline, it was for
an emacs feature that has since become smarter (and who cares about emacs
anyway). It is mentioned as the preferred way in PEP8, so it runs into some
disagreements from time to time. Most of the code in the projects has been
written with the older rule (yes on trailing newline) but I haven't been
blocking new code from not using it.


>
> FLAMEBAIT (filename):
>
> Some projects have a HACKING file, and some have a HACKING.rst file.
>  Doesn't .rst generally indicate a REST API definition?  I propose that the
> file be called HACKING.
>

HACKING.rst makes github format it correctly, let's move everything to rst.


>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
>