Excerpts from Clint Byrum's message of 2015-07-07 09:13:39 -0700: > Excerpts from Victor Stinner's message of 2015-07-07 08:22:26 -0700: > > Hi, > > > > Oslo libraries become more and more stable, cool :-) Sometimes, we have > > to modify APIs, to fix bugs, to deprecate functions, to add new function > > parameters, etc. It would be cool to _document_ these changes. Sphinx > > provides nice markups to document API changes: > > > > http://sphinx-doc.org/markup/para.html > > > > We can try to ensure that API changes are documented in reviews, or > > maybe also document old changes. > > > > Examples: > > > > .. versionadded:: 2.5 > > The *spam* parameter. > > > > .. versionadded:: 2.6 > > The function now returns an integer. > > > > .. deprecated:: 3.1 > > Use :func:`spam` instead. > > > > I noticed that the deprecated markup is already used in oslo.utils doc: > > > > http://docs.openstack.org/developer/oslo.utils/api/timeutils.html#oslo_utils.timeutils.isotime > > > > This is great information, thank you. > > Any time we have versions appearing in code or docs, I cringe, because > versions and releasing are separate from coding and documenting. > If I'm adding a parameter today in the latest commit after 1.0.0, I > really don't know if the next version released will be 1.1.0 or 2.0.0 > (I do know it won't be 1.0.1 because I have changed the API!). > > Or do we just make a rule that you _do_ get to choose the version bump > in the commit that changes the API, and if you say 1.1.0, and it becomes > 2.0.0 before release, thats ok because the versionadded is still accurate > even if 1.1.0 didn't release?
I expect that most of the time incrementing the minor version is going to be accurate (we've so far only had backwards-incompatible versions > 1.0 for removing the oslo namespace). However, if we find that a versionadded note references a version that was never actually released, we can treat that as a doc bug and go back and update it. Doug __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
