Open Stack

On Thu, Oct 15, 2015 at 5:52 AM, Victor Stinner <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.

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151015/509502e9/attachment.html>