[python-committers] build dependency on the branches on sphinx trunk necessary?

[Gregory P. Smith]

On Mon, Jan 26, 2009 at 1:59 PM, Matthias Klose <doko at ubuntu.com> wrote:

> Guido van Rossum schrieb:
> > On Mon, Jan 26, 2009 at 1:27 PM, Matthias Klose <doko at ubuntu.com> wrote:
> >> Guido van Rossum schrieb:
> >>> I'm not sure I understand your request. Is it okay to build docs using
> >>> a version of sphinx that is included in the distro? Is there a
> >>> specific revision that you would like to see rolled back, or do you
> >>> have a specific fix in mind?
> >> the specific change was committed in r68428. I didn't check if reverting
> this
> >> causes regressions in building the docs.
> >>
> >> A safe approach would be to only use build dependencies on a branch
> which were
> >> released before the first release of the branch. I assume in this case,
> the
> >> branch should stick with sphinx-0.5 and not rely on newer sphinx
> versions (or
> >> sphinx dependencies which were released after the python-2.6.0 release).
> >
> > This seems rather restrictive. It would mean that if we found a bug in
> > sphinx-0.5 that was fixed later in sphinx development we couldn't
> > depend on the bug being fixed for the lifetime of Python 2.6, to
> > satisfy this requirement. Ditto for new sphinx features that might
> > make life easier for the doc authors, or in some cases enable new
> > types of markup that would clarify the docs. It would make backporting
> > doc-fixes from 2.7 harder too.
>
> the rationale for this proposal is that when a Linux distribution does
> freeze
> for a release, only bug fixes are allowed during the freeze until the
> release.
> If you do consider a new release on the branch as a bug fix release which
> can be
> allowed during a freeze, but it depends on a new upstream release of it's
> build
> dependencies we still cannot include it because of the tightened build
> dependency.


Chances are very high that if you grab a copy of sphinx from svn on the date
of the python X.Y release in question that the docs for any updates to that
.Y release will always build using that sphinx.  If not, its up to you as
the interested party to fix/patch them.  I doubt that'll be much work.


>
> > I could live with "only depend on released versions of anything" but I
> > don't think I could live with "don't depend on anything released after
> > 2.6.0 was released" (which IIUC is what you are proposing here).
>
> I could live with a "don't depend on anything released after 2.6.0 was
> released,
> unless it is a bug fix release", e.g. allowing sphinx-0.5.x releases
> (assuming
> these don't have new features).
>
> I don't know of any other open source software which allows unlimited
> changes on
> the build requirements in this way on a release branch.


As a developer I don't consider the documentation to be a critical part of
the build since it isn't strictly tied to a particular release of python,
afaict they're only -guaranteed- to build using a sphinx available at the
time of any given release because that is what was used to make the release.
 Nothing else.

Bundling the required version of sphinx with future Python releases as Guido
suggests is not a bad idea.

If you want to pick a sphinx version to use with a particular python build,
find the date of the release tag for that python version and sync to sphinx
at that date.  It'll be up to you (debian package maintainers) to make sure
that the docs keep building with that version of sphinx within that release
branch.  That could involve patches if someone commits something that breaks
your assumption.  But lets be realistic: documentation changes post-release
are rare.  It won't be much, if any, work for the debian package maintainer.

-Greg
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-committers/attachments/20090126/9635039b/attachment-0001.htm>