Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Ihar Hrachyshka]

> On 16 Oct 2015, at 13:02, Victor Stinner  wrote:
> 
> Le 15/10/2015 17:54, Joshua Harlow a écrit :
>> 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.
> 
> I hope that we will not release *too* frequently. Oslo libraries are supposed 
> to be somehow "stable" :-) Past history showed that any minor change has 
> major impact on the OpenStack CI ;-)

Once we have all major gate jobs using constraints file from 
openstack/requirements, we should not affect CI and hence development pace. I 
think neutron gate is quite close to that goal (we already have -constraints 
jobs for pep8/doc/py* jobs), and I believe other projects should follow the 
lead.

Once we are there, no oslo release should break the world. That of course does 
not mean we can release breaking changes, but it should make mistakes less 
painful.

Ihar


signature.asc
Description: Message signed with OpenPGP using GPGMail
__
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

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Davanum Srinivas]

Victor,

I'd like to continue the fast paced oslo releases. Last fire drill showed,
a few projects that depended on internals of how things we implemented in
oslo libraries. Examples were oslo.policy switching to requests from
urllib3 and the oslo.utils how it deals with exceptions for example. These
are better caught early. We still have to get projects to honor the
contracts say in oslo.messaging (stop() needs to be called before wait())
etc as well. in spite of the many LOG messages over the last few months,
projects have not done so as well. IMHO, oslo already has a very early
freeze compared to other projects. So we should take the hit early in terms
of releasing and finding problems IMHO. yes, +1000 we have to be more
careful.

Yes, "major gate jobs using constraints file from openstack/requirements"
will help as well. So fyi, the travis jobs i set up for running a handful
of py27/py34 jobs of different projects against master of all oslo.*
libraries is green today (https://travis-ci.org/dims/). So we will have a
bunch of libraries released today. https://review.openstack.org/#/c/236770/.
Heads up :)

So Net, Oslo should continue to push out releases every late monday / early
tuesday (US eastern time). and i'd request all the Oslo cores to check
things out the end of previous week. So we can run all sorts of tests in
the weekend to make sure we don't break stuff.

Thanks,
Dims

On Mon, Oct 19, 2015 at 4:49 AM, Ihar Hrachyshka 
wrote:

> > On 16 Oct 2015, at 13:02, Victor Stinner  wrote:
> >
> > Le 15/10/2015 17:54, Joshua Harlow a écrit :
> >> 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.
> >
> > I hope that we will not release *too* frequently. Oslo libraries are
> supposed to be somehow "stable" :-) Past history showed that any minor
> change has major impact on the OpenStack CI ;-)
>
> Once we have all major gate jobs using constraints file from
> openstack/requirements, we should not affect CI and hence development pace.
> I think neutron gate is quite close to that goal (we already have
> -constraints jobs for pep8/doc/py* jobs), and I believe other projects
> should follow the lead.
>
> Once we are there, no oslo release should break the world. That of course
> does not mean we can release breaking changes, but it should make mistakes
> less painful.
>
> Ihar
>
> __
> 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
>
>


-- 
Davanum Srinivas :: https://twitter.com/dims
__
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

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Victor Stinner]

Le 15/10/2015 17:54, Joshua Harlow a écrit :

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.


I hope that we will not release *too* frequently. Oslo libraries are 
supposed to be somehow "stable" :-) Past history showed that any minor 
change has major impact on the OpenStack CI ;-)


If we have to choose between "documenting changes with the wrong version 
number" and "don't document changes", I pick the wrong version. IHMO 
it's better than doc at all.


As I replied to Brant, I don't expect so much issues between doc and 
version numbers.


In a few weeks, if we consider that we have too many issues between doc 
and versions, it would maybe be time to rethink how we release Oslo 
libraries? Maybe our release process should be enhanced to review more 
carefully changes before a release?


By the way, Sphinx has a great tool to extract *all* versionchanged and 
versionadded. It's super useful to prepare a change log for humans. But 
it can also help to check the documentation of changes before a release, 
maybe manual check at the beginning?


The most basic check is to compute the diff since the previous release 
and check manually all versionadded and versionchanged.



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


Hey, it remembers me CVS :-D It may work, but such tool has to be 
written first ;-) It may also make the release process more complex. 
Right now, it's quite simple: pick any Git SHA1 and this hash becomes 
your release. No *any* change between this revision and the final release.


Victor

__
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

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Joshua Harlow]

Victor Stinner wrote:

Le 15/10/2015 17:54, Joshua Harlow a écrit :

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.


I hope that we will not release *too* frequently. Oslo libraries are
supposed to be somehow "stable" :-) Past history showed that any minor
change has major impact on the OpenStack CI ;-)


Stability != releasing frequently (which is a good thing to do); 
stability IMHO is more about having stable API(s) but even with said 
API(s) bugs happen and new things get added. Overall point taken, we 
have to be careful (but I would hope this isn't unique to oslo, everyone 
in the community should be careful because in reality everyone is 
producing stable API(s) for consumption by someone else).




If we have to choose between "documenting changes with the wrong version
number" and "don't document changes", I pick the wrong version. IHMO
it's better than doc at all.

As I replied to Brant, I don't expect so much issues between doc and
version numbers.

In a few weeks, if we consider that we have too many issues between doc
and versions, it would maybe be time to rethink how we release Oslo
libraries? Maybe our release process should be enhanced to review more
carefully changes before a release?

By the way, Sphinx has a great tool to extract *all* versionchanged and
versionadded. It's super useful to prepare a change log for humans. But
it can also help to check the documentation of changes before a release,
maybe manual check at the beginning?

The most basic check is to compute the diff since the previous release
and check manually all versionadded and versionchanged.


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


Hey, it remembers me CVS :-D It may work, but such tool has to be
written first ;-) It may also make the release process more complex.
Right now, it's quite simple: pick any Git SHA1 and this hash becomes
your release. No *any* change between this revision and the final release.



+1 I remember that from CVS to, damn, that was a long time ago, ha.


Victor

__
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


__
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

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Brant Knudson]

On Thu, Oct 15, 2015 at 5:52 AM, Victor Stinner  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: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Joshua Harlow]

Brant Knudson wrote:



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




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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__
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

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Victor Stinner]

Le 15/10/2015 12:52, Victor Stinner a écrit :

I started to do this for the oslo.config library:
https://review.openstack.org/#/c/235232/


More changes.

oslo.concurrency:
https://review.openstack.org/#/c/235416/

oslo.serialization:
https://review.openstack.org/#/c/235297/

oslo.utils:
https://review.openstack.org/#/c/235386/

Victor

__
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

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Victor Stinner]

Le 15/10/2015 16:34, Brant Knudson a écrit :

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.


I propose to expect that the next release is X.Y+1 where X.Y is the 
current release. If the release manager wants to increase the major 
version number, it's very easy to fix all documentation at once. Example 
with sed in oslo.concurrency to replace 2.7 with 3.0:


   sed -i -e 's/\(versionadded\|versionchanged\):: 2.7/\1:: 3.0/g' \
  $(find oslo_concurrency/ -name "*.py")


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


If a the version X.Y+1 is released before the change is reviewed, the 
reviewer is responsible to complain about outdated 
versionadded/versionchanged markups.


I know that it adds more work, but I consider that it's worth it.


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.


It's maybe time to think outside OpenStack. Oslo libraries can be used 
outside OpenStack and API stability and documenting changes matters even 
more outside OpenStack.


I wrote 4 patches to document all changes of 4 Oslo Libraries 
(concurrency, config, serialization, utils). See my patches, they are 
quite small. I took me 2 hours to dig the whole Git history since the 
creation of each library. Only some patches changes the API. For 
example, bug fixes don't have to be documented.


Victor

__
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

Re: [openstack-dev] [oslo] Require documenting changes with versionadded and versionchanged

[Doug Hellmann]

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  > > 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-requ...@lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 

__
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