[openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

Victor Stinner vstinner at redhat.com
Thu Oct 15 10:52:27 UTC 2015


I propose that changes must now be documented in Oslo libraries. If a 
change is not documented, it must *not* be approved.

IMHO it's very important to document all changes. Otherwise, it becomes 
really hard to guess if a specific parameter or a specific function can 
be used just by reading the doc :-/ And we should not force users to 
always upgrading the Oslo libraries to the latest versions. It doesn't 
work on stable branches :-)

Currently, ".. versionadded:: x.y" and ".. versionchanged:: x.y" are not 
(widely) used in Oslo libraries. A good start would be to dig the Git 
history to add these tags. I started to do this for the oslo.config library:

I'm interested to write similar changes for other Oslo libraries.

Because I created this change, I started to vote -1 on all patches which 
oslo.config changes the API without documenting the doc.

What do you think?


More information about the OpenStack-dev mailing list