[Python-Dev] Move selected documentation repos to PSF BitBucket account?

[Georg Brandl]

On 11/23/2014 09:42 PM, Brett Cannon wrote:

>     The more problematic category are pre-push hooks.  We use them for checking
>     and rejecting commits with
> 
>     * disallowed branches
>     * non-conformant whitespace
>     * wrong EOL style
>     * multiple heads per named branch
> 
>     As far as I know, neither GH nor BB support such hooks, since they are highly
>     project-specific.  However, they are only used in cpython and related
>     repositories, so that doesn't concern migration of doc-only repos.
> 
>     Sure, you can let the CI run the checks, but that doesn't prohibit merging
>     and is circumvented by direct pushes to the repository that don't go through
>     the PR system.  (And please don't make me as a coredev open a PR for every
>     change.)
> 
> 
> I'm not even going to touch the idea of requiring code review for all patches in
> the middle of this discussion. =) 

As far as I can see, our Rietveld is very well used already.  *Requiring* code
review for *all* patches is detrimental in a volunteer project IMO.  (I'm saying
this especially because many of my changes are small to trivial doc fixes.)

>     The next point is that there is no easy way to change the target branch of
>     a pull request (on github or bitbucket).  People will usually make patches
>     against the master branch unless told differently explicitly, which means
>     that the pull request will also be against the master branch.  Which means,
>     close the PR, ask submitter to resubmit against 3.x branch, or do it
>     yourself.
> 
> 
> How do other projects tend to manage their bugfix vs. in-dev branches? Is it a
> lot of cherrypicking? Probably our long development cycles doesn't help with
> this as it makes cross-branch merging difficult thanks to divergence, else this
> could be automated somehow or simply not be an issue. Otherwise we would have to
> do a merge from branch to branch locally as we do now and make sure people
> committed in the branch we wanted them to.

For smaller projects, it's not as much of an issue.  In Sphinx, there are two
branches (stable and default), and when there are pull requests to the default
branch that should go to stable, I cherry-pick them manually.  And as you said,
merging or transplanting between branches is much more likely to succeed
automatically.

>     The "but it is much easier to contribute simple changes" argument is a bit
>     simplified: for any nontrivial patch, the time spent on working out the code
>     should outweight time spent with "hg diff" or "click on pull request".  And
>     while Travis CI is nice, running relevant tests locally is *much* quicker than
>     waiting for a full test suite run on a virtualized testing machine.
> 
> 
> Sure, but it's definitely easier to just wait for the Travis green on the PR
> than have to apply a patch and run the tests myself manually.

You'll likely have to run them manually anyway while merging to the other
branches.

>     As for typo fixes, the world does not end when some typos aren't fixed.
>     Anyway, for the docs we have an explicit offer to send anything, patch or
>     just suggestion, to docs at python.org <mailto:docs at python.org>, and people do
>     make use of it.  No
>     github account even required.
> 
> 
> Which is great, but I'm willing to bet clicking "Edit" in GitHub is easier still
> than creating the patch and emailing it. I have contributed doc fixes to a bunch
> of projects because of that "Edit" button (which is why I think Nick is so
> anxious to get it). If I had to do any checkout then I wouldn't have done them.
> And even having to email a diff might be too much for some changes.

I did say "patch or just suggestion".  Most emails to docs at python.org come
without a patch, just a plain description of what's wrong, and that is just
fine.  I would also judge that >50% of the emails come from people who wouldn't
have a github account in any case (so that the big shiny Edit button isn't an
easy option).

>     > And I'm still in support no matter what of breaking out the HOWTOs and the
>     > tutorial into their own repos for easier updating (having to update the Python
>     > porting HOWTO in three branches is a pain when it should be consistent across
>     > Python releases).
> 
>     I see no problem with that, provided there's a cronjob that syncs the version
>     in Doc/ to the external version reasonably often.
> 
> 
> Would that really be necessary? At least for the HOWTOs how often are they
> edited simultaneously as some code in CPython? The Clinic HOWTO is probably the
> only one that might get updated simultaneously. I'd also be curious to know how
> often the tutorial is updated simultaneously as well.

I'd like the HOWTOs to stay part of Doc/, so changes in the external repo have
to be merged in there somehow, and not only at release time.

Georg