[openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged
vstinner at redhat.com
Fri Oct 16 11:02:55 UTC 2015
Le 15/10/2015 17:54, Joshua Harlow a écrit :
> I had this problem with deprecation versioning (the debtcollector
> library functions take a version="XYZ", removal_version="ABC" params,
> and it is pretty hard to get those two numbers right, especially with
> weekly releases and not knowing when a review will merge... I'm not
> saying we shouldn't try to do this, but we just have to figure out how
> to do it in a smart way.
I hope that we will not release *too* frequently. Oslo libraries are
supposed to be somehow "stable" :-) Past history showed that any minor
change has major impact on the OpenStack CI ;-)
If we have to choose between "documenting changes with the wrong version
number" and "don't document changes", I pick the wrong version. IHMO
it's better than doc at all.
As I replied to Brant, I don't expect so much issues between doc and
In a few weeks, if we consider that we have too many issues between doc
and versions, it would maybe be time to rethink how we release Oslo
libraries? Maybe our release process should be enhanced to review more
carefully changes before a release?
By the way, Sphinx has a great tool to extract *all* versionchanged and
versionadded. It's super useful to prepare a change log for humans. But
it can also help to check the documentation of changes before a release,
maybe manual check at the beginning?
The most basic check is to compute the diff since the previous release
and check manually all versionadded and versionchanged.
> Perhaps there need to be a gerrit based way to add these, so for example
> a review submitter would write:
> ".. versionadded:: $FILL_ME_IN_WHEN_MERGED" and ".. versionchanged::
> $FILL_ME_IN_WHEN_MERGED" or something, and gerrit when merging code
> would change those into real numbers...
Hey, it remembers me CVS :-D It may work, but such tool has to be
written first ;-) It may also make the release process more complex.
Right now, it's quite simple: pick any Git SHA1 and this hash becomes
your release. No *any* change between this revision and the final release.
More information about the OpenStack-dev