← Back to team overview

openstack team mailing list archive

Re: documentation of flags, introducing of a naming convention for flags


Christian Berendt wrote:

> a) we should create a useful documentation including all flags

That's been identified as a necessary area of improvement for doc. I
plan to work on the raw info (organize them in themes and document their
use) and Anne should help me get it into the openstack manual.

It's a bit hard to keep up to date though. Ideally we would autogenerate
it from comments in code...

> b) we should introduce a naming convention for new flags and we should
> rename existing flags
> example:
> all flags related to default values are starting with "default_", all
> flags related to a path are starting with "path_".
> Looks like most of the flags have good names at the moment, but I think
> we should write it down in the wiki or the developer documentation to
> reduce the possibility of bad names in the future.

That's definitely something we should do, either in the RST developer
doc or as a CodingStandards subpage in the wiki. Christian: do you take
the lead on that ?

> c) if it's possible we should collect all flags in one file
> At the moment the flags are defined in the files where they are used. I
> think it would be nice to have on file, for example nova/flags.py,
> including all flags used all over the code.

I think there is a rationale for defining some flags locally. If not,
I'd support placing them all in flags.py with a comment about where they
apply, which could serve as a basis for an autogenerated doc.


Thierry Carrez (ttx)
Release Manager, OpenStack

Follow ups