Open Stack

Excerpts from Joshua Harlow's message of 2015-10-15 08:54:47 -0700:
> 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...

Gerrit can't change the commit because then the hash won't match.

Stand by for some announcements about release notes management coming
next week that will help solve this problem in a different way.

Doug

> 
> >
> > 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
>