[openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged
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