[openstack-dev] [python3][tc][infra][docs] changing the documentation build PTI to use tox

James E. Blair corvus at inaugust.com
Mon Jul 9 21:23:11 UTC 2018

Doug Hellmann <doug at doughellmann.com> writes:

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

Indeed, this is a situation where in many cases our intuition collides
with git's implementation.  We've always had this restriction with Zuul
(we can cause different jobs to run for different tags, but we can only
do so by matching the name of the tag, not the name of the branch that
people associate with the tag).  If we were very consistent about
release version numbers and branches across projects, we could write
some configuration which ran python2 jobs on some releases and python3
jobs on others.  But we aren't in that position, and doing so would
require a jumble of regexes, different for each project.

In Zuul v3, since much of the configuration is in-repo, the desire to
alter tag/release jobs based on the content in-repo is even closer to
the surface.  So the desire to handle this situation better is growing,
and I think stands on its own merit.  To that end, we've started
exploring some changes to Zuul in that direction.  One of them is here:

But, even if we do land that change, I think the PTI change that Doug is
proposing is the best thing for us to do in this situation.  We made the
PTI so that we have a really simple interface and line of demarcation
where we say that, collectively, we want all projects to be able to
build docs, and we're going to build a bunch of automation around that,
but the PTI is the boundary between that automation and the in-repo
content.  It has served us very well through a number of changes to how
we run unit tests.  The fact that we've gone through far fewer changes
to how docs are built has perhaps led us to think that we didn't need
the layer of abstraction that tox provided us.  However, as soon as we
removed it, we encountered a situation where, in fact, it would have
insulated us.

Put another way, I think the spirit of the PTI is about finding the
right place where the automation that we build for all the projects
stops, and the project-specific implementation begins.  Facilitating a
project saying "this project needs python3 to build docs" in a way that
is independent of the automation system is the best outcome.


More information about the OpenStack-dev mailing list