← Back to team overview

openstack team mailing list archive

Re: Being pedantic about pedanticism: HACKING styleguide


.rst is ReStructured Text.  It's the markup language being used.



> -----Original Message-----
> From: openstack-bounces+ewan.mellor=citrix.com@xxxxxxxxxxxxxxxxxxx
> [mailto:openstack-bounces+ewan.mellor=citrix.com@xxxxxxxxxxxxxxxxxxx]
> On Behalf Of Andrew Bogott
> Sent: Thursday, March 22, 2012 9:22 AM
> To: openstack@xxxxxxxxxxxxxxxxxxx
> Subject: [Openstack] Being pedantic about pedanticism: HACKING
> styleguide
>      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.
> 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.