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