Open Stack

Excerpts from Zane Bitter's message of 2018-07-09 11:04:28 -0400:
> On 05/07/18 16:46, Doug Hellmann wrote:
> > I have a governance patch up [1] to change the project-testing-interface
> > (PTI) for building documentation to restore the use of tox.
> > 
> > We originally changed away from tox because we wanted to have a
> > single standard command that anyone could use to build the documentation
> > for a project. It turns out that is more complicated than just
> > running sphinx-build in a lot of cases anyway, because of course
> > you have a bunch of dependencies to install before sphinx-build
> > will work.
> 
> Is this the main reason? If we think we made the wrong call (i.e. 
> everyone has to set up a virtualenv and install doc/requirements.txt 
> anyway so we should just make them use tox even if they are not Python 
> projects), then I agree it makes sense to fix it even though we only 
> _just_ finished telling people it would be the opposite way.

Yes, we made the wrong call when we set the PTI to not use tox for these
cases.

> > Updating the job that uses sphinx directly to run under python 3,
> > while allowing the transition to be self-testing, was going to
> > require writing some extra complexity to look at something in the
> > repository to decide what version of python to use.  Since tox
> > handles that for us by letting us set basepython in the virtualenv
> > configuration, it seemed more straightforward to go back to using
> > tox.
> 
> Wouldn't another option be to have separate Zuul jobs for Python 3 and 
> Python 2-based sphinx builds? Then the switchover would still be 
> self-testing.
> 
> I'd rather do that if this is the main problem we're trying to solve, 
> rather than reverse course.

These jobs run on tag events, which are not "branch aware" (tags
can be on 0 or more branches at the same time). That means we cannot
have different versions of the job running for different branches.

Instead we need 1 job, which uses data inside the repository to
decide exactly what to do. Instead of writing a new, more complicated,
job to look at a flag file or other settings to decide whether to
run sphinx under python 2 or 3, it will be simpler to go back to
using the old existing tox-based job and to use the tox configuration
to control the version of python. Using the tox job also has the
benefit of fixing the tox-siblings issue for projects like neutron
plugins that need neutron installed in order to generate their
documentation. So we fix 2 problems with 1 change.

We actually have a similar problem for the release job, but in that
case we don't need tox because we don't need to install any
dependencies in order to build the artifacts.  I have tested building
sdists and wheels from every repo with a setup.py and did not find
any failures related to using python 3, so we can just switch
everyone over to use the new job.

> 
> > So, this new PTI definition restores the use of tox and specifies
> > a "docs" environment. I have started defining the relevant jobs [2]
> > and project templates [3], and I will be updating the python3-first
> > transition plan as well.
> > 
> > Let me know if you have any questions about any of that,
> > Doug
> > 
> > [1] https://review.openstack.org/#/c/580495/
> > [2] https://review.openstack.org/#/q/project:openstack-infra/project-config+topic:python3-first
> > [3] https://review.openstack.org/#/q/project:openstack-infra/openstack-zuul-jobs+topic:python3-first
> > 
> > __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> > 
>