Re: [openstack-dev] [all][oslo] pbr potential breaking change coming

[Markus Zoeller]

On 13.07.2016 19:11, Jeremy Stanley wrote:
> On 2016-07-13 13:25:44 +0200 (+0200), Markus Zoeller wrote:
>> For some reason the gate docs job didn't find the issue (wrong json
>> format) which got fixed with change [1]. It doesn't even emit a warning.
>> Locally, the execution of "tox -e docs" does find the issue. Can we make
>> the gate docs job aware of such json format issues?
> [...]
> 
> It looks like your "docs" tox env is doing some additional checks[1]
> with the json.tool module. The gate-{name}-docs CI jobs don't call
> `tox -e docs` but `tox -evenv -- python setup.py build_sphinx`
> directly[2]. Changing that has been discussed[3][4] (and
> rejected/withdrawn) by the TC in the past.
> 
> I agree with Andreas that if you want additional checking of this
> you probably need it in a different job. The same goes for tests of
> your config/policy generation and API guide/reference builds. The
> goal of gate-{name}-docs is to make sure that the setup.py
> build_sphinx entrypoint works across all covered projects (per the
> CTI[5]) without requiring any extra nonstandard magic.
> 
> [1] http://git.openstack.org/cgit/openstack/nova/tree/tox.ini?id=df0aa8a#n97
> [2] 
> http://git.openstack.org/cgit/openstack-infra/project-config/tree/jenkins/scripts/run-docs.sh
> [3] 
> http://eavesdrop.openstack.org/meetings/tc/2014/tc.2014-09-30-20.01.log.html#l-27
> [4] https://review.openstack.org/119875
> [5] 
> http://governance.openstack.org/reference/cti/python_cti.html#documentation
> 

I understand the reasoning now, thanks. Luckily, Andreas pushed a patch
to change that for Nova: https://review.openstack.org/#/c/341444/1

-- 
Regards, Markus Zoeller (markus_z)


__
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] [all][oslo] pbr potential breaking change coming

[Jeremy Stanley]

On 2016-07-13 13:25:44 +0200 (+0200), Markus Zoeller wrote:
> For some reason the gate docs job didn't find the issue (wrong json
> format) which got fixed with change [1]. It doesn't even emit a warning.
> Locally, the execution of "tox -e docs" does find the issue. Can we make
> the gate docs job aware of such json format issues?
[...]

It looks like your "docs" tox env is doing some additional checks[1]
with the json.tool module. The gate-{name}-docs CI jobs don't call
`tox -e docs` but `tox -evenv -- python setup.py build_sphinx`
directly[2]. Changing that has been discussed[3][4] (and
rejected/withdrawn) by the TC in the past.

I agree with Andreas that if you want additional checking of this
you probably need it in a different job. The same goes for tests of
your config/policy generation and API guide/reference builds. The
goal of gate-{name}-docs is to make sure that the setup.py
build_sphinx entrypoint works across all covered projects (per the
CTI[5]) without requiring any extra nonstandard magic.

[1] http://git.openstack.org/cgit/openstack/nova/tree/tox.ini?id=df0aa8a#n97
[2] 
http://git.openstack.org/cgit/openstack-infra/project-config/tree/jenkins/scripts/run-docs.sh
[3] 
http://eavesdrop.openstack.org/meetings/tc/2014/tc.2014-09-30-20.01.log.html#l-27
[4] https://review.openstack.org/119875
[5] http://governance.openstack.org/reference/cti/python_cti.html#documentation
-- 
Jeremy Stanley

__
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] [all][oslo] pbr potential breaking change coming

[Andreas Jaeger]

On 2016-07-13 13:25, Markus Zoeller wrote:
> For some reason the gate docs job didn't find the issue (wrong json
> format) which got fixed with change [1]. It doesn't even emit a warning.
> Locally, the execution of "tox -e docs" does find the issue. Can we make
> the gate docs job aware of such json format issues?

Just move that change from docs to pep8 target,
Andreas

> References:
> [1] https://review.openstack.org/#/c/339295/1


-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


__
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] [all][oslo] pbr potential breaking change coming

[Markus Zoeller]

On 23.06.2016 12:21, Andreas Jaeger wrote:
> On 06/23/2016 10:43 AM, Markus Zoeller wrote:
>> On 21.06.2016 15:01, Doug Hellmann wrote:
>>> A while back pbr had a feature that let projects pass "warnerror"
>>> through to Sphinx during documentation builds, causing any warnings in
>>> that build to be treated as an error and fail the build. This lets us
>>> avoid things like links to places that don't exist in the docs, bad but
>>> renderable rst, typos in directive or role names, etc.
>>>
>>> Somewhat more recently, but still a while ago, that feature "broke"
>>> with a Sphinx release that was not API compatible. Sachi King has
>>> fixed this issue within pbr, and so the next release of pbr will
>>> fix the broken behavior and start correctly passing warnerror again.
>>> That may result in doc builds breaking where they didn't before.
>>>
>>> The short-term solution is to turn of warnerrors (look in your
>>> setup.cfg), then fix the issues and turn it back on. Or you could
>>> preemptively fix any existing warnings in your doc builds before the
>>> release, but it's simple enough to turn off the feature if there isn't
>>> time.
>>>
>>> Josh, Sachi, & other Oslo folks, I think we should hold off on
>>> releasing until next week to give folks time. Is that OK?
>>>
>>> Doug
>>>
>>> PS - Thanks, Sachi, I know that bug wasn't a ton of fun to fix!
>> [...]
>>
>> Thanks for the heads up. I checked Nova, and every sphinx-build command
>> we use in our "tox.ini" file already uses the -W flag to treat warnings
>> as errors. I guess we're safe with that?
>>
> 
> Infra calls the docs job using
> tox -e venv -- python setup.py build_sphinx
> 
> And that's where the change comes in...
> 
> So, your docs environment is not used as is in the gate,
> 
> Andreas
> 

For some reason the gate docs job didn't find the issue (wrong json
format) which got fixed with change [1]. It doesn't even emit a warning.
Locally, the execution of "tox -e docs" does find the issue. Can we make
the gate docs job aware of such json format issues?

References:
[1] https://review.openstack.org/#/c/339295/1

-- 
Regards, Markus Zoeller (markus_z)


__
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] [all][oslo] pbr potential breaking change coming

[Flavio Percoco]

On 21/06/16 09:01 -0400, Doug Hellmann wrote:

A while back pbr had a feature that let projects pass "warnerror"
through to Sphinx during documentation builds, causing any warnings in
that build to be treated as an error and fail the build. This lets us
avoid things like links to places that don't exist in the docs, bad but
renderable rst, typos in directive or role names, etc.

Somewhat more recently, but still a while ago, that feature "broke"
with a Sphinx release that was not API compatible. Sachi King has
fixed this issue within pbr, and so the next release of pbr will
fix the broken behavior and start correctly passing warnerror again.
That may result in doc builds breaking where they didn't before.

The short-term solution is to turn of warnerrors (look in your
setup.cfg), then fix the issues and turn it back on. Or you could
preemptively fix any existing warnings in your doc builds before the
release, but it's simple enough to turn off the feature if there isn't
time.

Josh, Sachi, & other Oslo folks, I think we should hold off on
releasing until next week to give folks time. Is that OK?

Doug

PS - Thanks, Sachi, I know that bug wasn't a ton of fun to fix!


Glance should be ok and I've just proposed a patch like Ihar's for Zaqar.

Flavio

--
@flaper87
Flavio Percoco


signature.asc
Description: PGP signature
__
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] [all][oslo] pbr potential breaking change coming

[Jeremy Stanley]

On 2016-06-23 13:44:36 +0200 (+0200), Markus Zoeller wrote:
> Interesting, I didn't know that. It runs without warnings in Nova too,
> so hopefully everything's in a good shape for the pbr release. :)

Note that there has been at least one past proposal[1] to add a
"docs" tox environment as mandated in the CTI[2] for official
projects in Python, but it was rejected over concerns it would
encourage projects to run arbitrary commands before/after the Sphinx
build rather than implementing proper plugins.

[1] https://review.openstack.org/119875
[2] 
http://governance.openstack.org/reference/cti/python_cti.html#specific-commands
-- 
Jeremy Stanley

__
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] [all][oslo] pbr potential breaking change coming

[Markus Zoeller]

On 23.06.2016 12:21, Andreas Jaeger wrote:
> On 06/23/2016 10:43 AM, Markus Zoeller wrote:
>> On 21.06.2016 15:01, Doug Hellmann wrote:
>>> A while back pbr had a feature that let projects pass "warnerror"
>>> through to Sphinx during documentation builds, causing any warnings in
>>> that build to be treated as an error and fail the build. This lets us
>>> avoid things like links to places that don't exist in the docs, bad but
>>> renderable rst, typos in directive or role names, etc.
>>>
>>> Somewhat more recently, but still a while ago, that feature "broke"
>>> with a Sphinx release that was not API compatible. Sachi King has
>>> fixed this issue within pbr, and so the next release of pbr will
>>> fix the broken behavior and start correctly passing warnerror again.
>>> That may result in doc builds breaking where they didn't before.
>>>
>>> The short-term solution is to turn of warnerrors (look in your
>>> setup.cfg), then fix the issues and turn it back on. Or you could
>>> preemptively fix any existing warnings in your doc builds before the
>>> release, but it's simple enough to turn off the feature if there isn't
>>> time.
>>>
>>> Josh, Sachi, & other Oslo folks, I think we should hold off on
>>> releasing until next week to give folks time. Is that OK?
>>>
>>> Doug
>>>
>>> PS - Thanks, Sachi, I know that bug wasn't a ton of fun to fix!
>> [...]
>>
>> Thanks for the heads up. I checked Nova, and every sphinx-build command
>> we use in our "tox.ini" file already uses the -W flag to treat warnings
>> as errors. I guess we're safe with that?
>>
> 
> Infra calls the docs job using
> tox -e venv -- python setup.py build_sphinx
> 
> And that's where the change comes in...
> 
> So, your docs environment is not used as is in the gate,
> 
> Andreas
> 

Interesting, I didn't know that. It runs without warnings in Nova too,
so hopefully everything's in a good shape for the pbr release. :)

-- 
Regards, Markus Zoeller (markus_z)


__
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] [all][oslo] pbr potential breaking change coming

[Andreas Jaeger]

On 06/23/2016 10:43 AM, Markus Zoeller wrote:

On 21.06.2016 15:01, Doug Hellmann wrote:

A while back pbr had a feature that let projects pass "warnerror"
through to Sphinx during documentation builds, causing any warnings in
that build to be treated as an error and fail the build. This lets us
avoid things like links to places that don't exist in the docs, bad but
renderable rst, typos in directive or role names, etc.

Somewhat more recently, but still a while ago, that feature "broke"
with a Sphinx release that was not API compatible. Sachi King has
fixed this issue within pbr, and so the next release of pbr will
fix the broken behavior and start correctly passing warnerror again.
That may result in doc builds breaking where they didn't before.

The short-term solution is to turn of warnerrors (look in your
setup.cfg), then fix the issues and turn it back on. Or you could
preemptively fix any existing warnings in your doc builds before the
release, but it's simple enough to turn off the feature if there isn't
time.

Josh, Sachi, & other Oslo folks, I think we should hold off on
releasing until next week to give folks time. Is that OK?

Doug

PS - Thanks, Sachi, I know that bug wasn't a ton of fun to fix!

[...]

Thanks for the heads up. I checked Nova, and every sphinx-build command
we use in our "tox.ini" file already uses the -W flag to treat warnings
as errors. I guess we're safe with that?



Infra calls the docs job using
tox -e venv -- python setup.py build_sphinx

And that's where the change comes in...

So, your docs environment is not used as is in the gate,

Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
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] [all][oslo] pbr potential breaking change coming

[Markus Zoeller]

On 21.06.2016 15:01, Doug Hellmann wrote:
> A while back pbr had a feature that let projects pass "warnerror"
> through to Sphinx during documentation builds, causing any warnings in
> that build to be treated as an error and fail the build. This lets us
> avoid things like links to places that don't exist in the docs, bad but
> renderable rst, typos in directive or role names, etc.
> 
> Somewhat more recently, but still a while ago, that feature "broke"
> with a Sphinx release that was not API compatible. Sachi King has
> fixed this issue within pbr, and so the next release of pbr will
> fix the broken behavior and start correctly passing warnerror again.
> That may result in doc builds breaking where they didn't before.
> 
> The short-term solution is to turn of warnerrors (look in your
> setup.cfg), then fix the issues and turn it back on. Or you could
> preemptively fix any existing warnings in your doc builds before the
> release, but it's simple enough to turn off the feature if there isn't
> time.
> 
> Josh, Sachi, & other Oslo folks, I think we should hold off on
> releasing until next week to give folks time. Is that OK?
> 
> Doug
> 
> PS - Thanks, Sachi, I know that bug wasn't a ton of fun to fix!
> 
> __
> 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
> 

Thanks for the heads up. I checked Nova, and every sphinx-build command
we use in our "tox.ini" file already uses the -W flag to treat warnings
as errors. I guess we're safe with that?

-- 
Regards, Markus Zoeller (markus_z)


__
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] [all][oslo] pbr potential breaking change coming

[Doug Hellmann]

Excerpts from Ihar Hrachyshka's message of 2016-06-21 15:40:45 +0200:
> 
> > On 21 Jun 2016, at 15:01, Doug Hellmann  wrote:
> > 
> > A while back pbr had a feature that let projects pass "warnerror"
> > through to Sphinx during documentation builds, causing any warnings in
> > that build to be treated as an error and fail the build. This lets us
> > avoid things like links to places that don't exist in the docs, bad but
> > renderable rst, typos in directive or role names, etc.
> > 
> > Somewhat more recently, but still a while ago, that feature "broke"
> > with a Sphinx release that was not API compatible. Sachi King has
> > fixed this issue within pbr, and so the next release of pbr will
> > fix the broken behavior and start correctly passing warnerror again.
> > That may result in doc builds breaking where they didn't before.
> > 
> > The short-term solution is to turn of warnerrors (look in your
> > setup.cfg), then fix the issues and turn it back on. Or you could
> > preemptively fix any existing warnings in your doc builds before the
> > release, but it's simple enough to turn off the feature if there isn't
> > time.
> 
> Thanks a lot for the heads-up. I pushed the following patch for neutron: 
> https://review.openstack.org/332145
> 
> I don’t fix warnings that may be currently in the tree. I will do it once we 
> have a new pbr release: even if I would fix warnings we may have now, it 
> wouldn’t give any guarantee to us that nothing would sneak into the tree 
> after my fix. So I prefer just wait for new pbr and then fix it all in one go.
> 
> Ihar

That approach makes sense.

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

Re: [openstack-dev] [all][oslo] pbr potential breaking change coming

[Ihar Hrachyshka]

> On 21 Jun 2016, at 15:01, Doug Hellmann  wrote:
> 
> A while back pbr had a feature that let projects pass "warnerror"
> through to Sphinx during documentation builds, causing any warnings in
> that build to be treated as an error and fail the build. This lets us
> avoid things like links to places that don't exist in the docs, bad but
> renderable rst, typos in directive or role names, etc.
> 
> Somewhat more recently, but still a while ago, that feature "broke"
> with a Sphinx release that was not API compatible. Sachi King has
> fixed this issue within pbr, and so the next release of pbr will
> fix the broken behavior and start correctly passing warnerror again.
> That may result in doc builds breaking where they didn't before.
> 
> The short-term solution is to turn of warnerrors (look in your
> setup.cfg), then fix the issues and turn it back on. Or you could
> preemptively fix any existing warnings in your doc builds before the
> release, but it's simple enough to turn off the feature if there isn't
> time.

Thanks a lot for the heads-up. I pushed the following patch for neutron: 
https://review.openstack.org/332145

I don’t fix warnings that may be currently in the tree. I will do it once we 
have a new pbr release: even if I would fix warnings we may have now, it 
wouldn’t give any guarantee to us that nothing would sneak into the tree after 
my fix. So I prefer just wait for new pbr and then fix it all in one go.

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