[Python-Dev] Moving the developer docs?

[R. David Murray]

On Thu, 23 Sep 2010 10:41:35 -0400, Barry Warsaw <barry at python.org> wrote:
> On Sep 23, 2010, at 09:06 AM, Benjamin Peterson wrote:
> >Are any of our docs subject to release schedules?
> 
> I guess what I'm concerned about is this scenario:
> 
> You're a developer who has the source code to Python 3.1.  You read the
> in-tree docs to get a sense of how our development process works.  Now, you're
> a diligent and eager new contributor so you follow those instructions to the
> letter.  Unfortunately, Python 3.5 is the current version and we've changed
> key parts of the process.  There's no possible way that your 3.1 in-tree docs
> can be updated to reflect the new process.

Except for major changes like the transition to hg, the dev process is
no more likely to change than the code base (probably less!).  That is,
the eager developers with the 3.1 source code are just as likely to
produce a patch that won't be useful because it doesn't apply to the
current maintained versions as they are to encounter a piece of the dev
process that has changed enough to break what they tried to do.  (In this
context, the switch to hg is analogous to the switch to Python3...)

Also, the existence of the docs in the repository is (IMO) for *editing*
convenience.  The real place a new developer will be looking at the docs
is on the web site, just as the place most people (even developers,
unless I miss my guess; I know I do) look for Python documentation is
on the web site.  And that version will be up to date.

> Okay, we can tell you to get the Python 3.5 code, or probably better yet, the
> Python 3.6 in-development trunk, but now we've got another dilemma.  If we
> change the process in 3.6, there will be pressure to update the docs in 3.5
> and previous versions that are still officially maintained.  And what about
> security-only versions of Python?

Yes, and?  We update the docs of the maintained Python versions all
the time.  Doc backports are standard (even if Georg does most of them
in batches) unless the documentation is about a new feature.  The fact
that even 'new features' of the dev process would also get backported
is merely a detail.

We don't update docs for security releases as far as I know, so I would
expect we wouldn't update the dev docs either.

> Our development processes are *primarily* independent of Python version, so I
> don't think they should be tied to our source tree, and our CPython source
> tree at that.  I suspect the version-dependent instructions will be minimal
> and can be handled by the rare footnotes or whatever.

I don't think our development process applies to anything other than
the CPython source.  (At least at the moment...if we break out the
stdlib that will change, but at that point the stdlib should have its
own distinct development process, even if that process shares most of
its features with the CPython one.)

Our documentation is *primarily* independent of Python version, too, if
you go by the ratio of the word count of the substantive changes from
version to version to the word count of the docs as a whole :)  True,
the dev docs are even more independent, but I don't see that as trumping
the convenience to the developers of having them in the source tree.

A separate repository would also be fine, IMO.  If someone can find or
write the code to publish that repository to the appropriate location
automatically, we could presumably do this even before the rest of the
hg transition.

--David