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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
