[openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged
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
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
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