Brant Knudson wrote:
On Thu, Oct 15, 2015 at 5:52 AM, Victor Stinner <[email protected]
<mailto:[email protected]>> wrote:
Hi,
I propose that changes must now be documented in Oslo libraries. If
a change is not documented, it must *not* be approved.
IMHO it's very important to document all changes. Otherwise, it
becomes really hard to guess if a specific parameter or a specific
function can be used just by reading the doc :-/ And we should not
force users to always upgrading the Oslo libraries to the latest
versions. It doesn't work on stable branches :-)
Currently, ".. versionadded:: x.y" and ".. versionchanged:: x.y" are
not (widely) used in Oslo libraries. A good start would be to dig
the Git history to add these tags. I started to do this for the
oslo.config library:
https://review.openstack.org/#/c/235232/
I'm interested to write similar changes for other Oslo libraries.
Because I created this change, I started to vote -1 on all patches
which oslo.config changes the API without documenting the doc.
What do you think?
Victor
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.
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).
We have the same problem with documenting when something is deprecated.
+1
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.
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...
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.
:: Brant
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
