<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Oct 15, 2015 at 5:52 AM, Victor Stinner <span dir="ltr"><<a href="mailto:vstinner@redhat.com" target="_blank">vstinner@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi,<br>
<br>
I propose that changes must now be documented in Oslo libraries. If a change is not documented, it must *not* be approved.<br>
<br>
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 :-)<br>
<br>
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:<br>
<a href="https://review.openstack.org/#/c/235232/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/235232/</a><br>
<br>
I'm interested to write similar changes for other Oslo libraries.<br>
<br>
Because I created this change, I started to vote -1 on all patches which oslo.config changes the API without documenting the doc.<br>
<br>
What do you think?<br> 
<br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Victor<br>
<br></blockquote><div><br><div>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.<br><br>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).<br><br>We have the same problem with documenting when something is deprecated.<br><div><br></div></div><div>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.<br></div><div><br></div><div>:: Brant<br><br></div></div></div></div></div>