Open Stack

On 25/04/18 11:41, Doug Hellmann wrote:
> Excerpts from Sean McGinnis's message of 2018-04-25 09:59:13 -0500:
>>>>>>
>>>>>> I'd be more in favour of changing the zuul job to build with the '-W'
>>>>>> flag. To be honest, there is no good reason to not have this flag
>>>>>> enabled. I'm not sure that will be a popular opinion though as it may
>>>>>> break some projects' builds (correctly, but still).
>>>>>>
>>>>>> I'll propose a patch against zuul-jobs and see what happens :)
>>>>>>
>>>>>> Stephen
>>>>>>
>>>>>
>>>>> I am in favor of this too. We will probably need to give some teams some time
>>>>> to get warnings fixed though. I haven't done any kind of extensive audit of
>>>>> projects, but from a few I looked through, there are definitely a few that are
>>>>> not erroring on warnings and are likely to be blocked if we suddenly flipped
>>>>> the switch and errored on those.
>>>>>
>>>>> This is a legitimate issue though. In Cinder we had -W in the tox docs job, but
>>>>> since that is no longer being enforced in the gate, running "tox -e docs" from
>>>>> a fresh clone of master was failing. We really do need some way to enforce this
>>>>> so things like that do not happen.
>>>>
>>>> This. While forcing work on teams to do busywork is undeniably A Very
>>>> Bad Thing (TM), I do think the longer we leave this, the worse it'll
>>>> get. The zuul-jobs [1] patch will probably introduce some pain for
>>>> projects but it seems like inevitable pain and we're in the right part
>>>> of the cycle in which to do something like this. I'd be willing to help
>>>> projects fix issues they encounter, which I expect will be minimal for
>>>> most projects.
>>>
>>> I too think enforcing -W is the way to go, so count me in for the
>>> broken docs build help.
>>>
>>> Thanks for pushing this forward!
>>>
>>> Cheers,
>>> pk
>>>
>>
>> In support of this I have proposed [1]. To make it easier to transition (since
>> I'm pretty sure this will involve a lot of work by some projects) and since we
>> want to eventually have everything run under Python 3, I have just proposed
>> setting this flag as the default for the publish-openstack-sphinx-docs-python3
>> job template. Then projects can opt in as they are ready for both the
>> warnings-as-errors and Python 3 support.
>>
>> I would love to hear if there are any concerns about doing things this way or
>> if anyone has any better suggestions.
>>
>> Thanks!
>> Sean
>>
>> [1] https://review.openstack.org/#/c/564232/
>>
> 
> The only concern I have is that it may slow the transition to the
> python 3 version of the jobs, since someone would have to actually
> fix the warnings before they could add the new job. I'm not sure I
> want to couple the tasks of fixing doc build warnings with also
> making those docs build under python 3 (which is usually quite
> simple).
> 
> Is there some other way to enable this flag independently of the move to
> the python3 job?

The existing proposal is:

https://review.openstack.org/559348

TL;DR if you still have a build_sphinx section in setup.cfg then 
defaults will remain the same, but when removing it as part of the 
transition to the new PTI you'll have to eliminate any warnings. 
(Although AFAICT it doesn't hurt to leave that section in place as long 
as you need, and you can still do the rest of the PTI conversion.)

The hold-up is that the job in question is also potentially used by 
other Zuul users outside of OpenStack - including those who aren't using 
pbr at all (i.e. there's no setup.cfg). So we need to warn those folks 
to prepare.

cheers,
Zane.