Open Stack

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 ;-)

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.

Victor