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

Victor Stinner vstinner at redhat.com
Thu Oct 15 15:22:40 UTC 2015

Le 15/10/2015 16:34, Brant Knudson a écrit :
> Submitters don't know what release their change is going to get into.
> They might submit the review when version 1.1.0 is current so they mark
> it with added in 1.2.0, but then the change doesn't get merged until
> after 1.4.0 is tagged. Also, the submitter doesn't know what the next
> release is going to be tagged as, since it might be 1.2.0 or it might be
> 2.0.0.

I propose to expect that the next release is X.Y+1 where X.Y is the 
current release. If the release manager wants to increase the major 
version number, it's very easy to fix all documentation at once. Example 
with sed in oslo.concurrency to replace 2.7 with 3.0:

    sed -i -e 's/\(versionadded\|versionchanged\):: 2.7/\1:: 3.0/g' \
       $(find oslo_concurrency/ -name "*.py")

> So this will create extra churn as reviews have to be updated with the
> release #, and the docs will likely be wrong when reviewers forget to
> check it (unless this can be automated).

If a the version X.Y+1 is released before the change is reviewed, the 
reviewer is responsible to complain about outdated 
versionadded/versionchanged markups.

I know that it adds more work, but I consider that it's worth it.

> I don't think it's worth it to document in which release something is
> added in the oslo libs. We're not charging for this stuff so if you want
> the online docs to match your code use the latest. Or check out the tag
> and generate the docs for the release you're on to look at to see if the
> feature is there.

It's maybe time to think outside OpenStack. Oslo libraries can be used 
outside OpenStack and API stability and documenting changes matters even 
more outside OpenStack.

I wrote 4 patches to document all changes of 4 Oslo Libraries 
(concurrency, config, serialization, utils). See my patches, they are 
quite small. I took me 2 hours to dig the whole Git history since the 
creation of each library. Only some patches changes the API. For 
example, bug fixes don't have to be documented.


More information about the OpenStack-dev mailing list