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

Joshua Harlow harlowja at fastmail.com
Fri Oct 16 15:26:15 UTC 2015

Victor Stinner wrote:
> 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,
>> see
>> http://docs.openstack.org/developer/debtcollector/examples.html#further-customizing-the-emitted-messages)
>> 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 ;-)

Stability != releasing frequently (which is a good thing to do); 
stability IMHO is more about having stable API(s) but even with said 
API(s) bugs happen and new things get added. Overall point taken, we 
have to be careful (but I would hope this isn't unique to oslo, everyone 
in the community should be careful because in reality everyone is 
producing stable API(s) for consumption by someone else).

> 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
> version numbers.
> 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.

+1 I remember that from CVS to, damn, that was a long time ago, ha.

> Victor
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

More information about the OpenStack-dev mailing list