Open Stack

Brant Knudson wrote:
>
>
> On Thu, Oct 15, 2015 at 5:52 AM, Victor Stinner <vstinner at redhat.com
> <mailto:vstinner at redhat.com>> 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: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev