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