[Python-checkins] peps: PEP 462 now proposes Kallithea as the review component

[nick.coghlan]

https://hg.python.org/peps/rev/33f7f6d4fcb9
changeset:   5683:33f7f6d4fcb9
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sun Feb 01 12:59:34 2015 +1000
summary:
  PEP 462 now proposes Kallithea as the review component

files:
  pep-0462.txt |  188 ++++++++++++++++++++------------------
  pep-0474.txt |   57 +++++++++++-
  2 files changed, 157 insertions(+), 88 deletions(-)


diff --git a/pep-0462.txt b/pep-0462.txt
--- a/pep-0462.txt
+++ b/pep-0462.txt
@@ -8,7 +8,7 @@
 Content-Type: text/x-rst
 Requires: 474
 Created: 23-Jan-2014
-Post-History: 25-Jan-2014, 27-Jan-2014
+Post-History: 25-Jan-2014, 27-Jan-2014, 01-Feb-2015
 
 
 Abstract
@@ -26,8 +26,8 @@
 PEP Deferral
 ============
 
-This PEP is currently deferred pending updates to redesign it around
-the proposal in PEP 474 to create a Kallithea-based forge.python.org service.
+This PEP is currently deferred pending acceptance or rejection of the
+Kallithea-based forge.python.org proposal in PEP 474.
 
 
 Rationale for changes to the core development workflow
@@ -139,9 +139,11 @@
 * For core developers, the branch wrangling for bug fixes is delicate and
   easy to get wrong. Conflicts on the NEWS file and push races when
   attempting to upload changes add to the irritation of something most of
-  us aren't being paid to spend time on. The time we spend actually getting
-  a change merged is time we're not spending coding additional changes,
-  writing or updating documentation or reviewing contributions from others.
+  us aren't being paid to spend time on (and for those that are, contributing
+  to CPython is likely to be only one of our responsibilities). The time we
+  spend actually getting a change merged is time we're not spending coding
+  additional changes, writing or updating documentation or reviewing
+  contributions from others.
 * Red buildbots make life difficult for other developers (since a local
   test failure may *not* be due to anything that developer did), release
   managers (since they may need to enlist assistance cleaning up test
@@ -172,13 +174,17 @@
 * Rietveld (also hosted on bugs.python.org) for code review
 * Buildbot (buildbot.python.org) for automated testing
 
-This proposal does *not* currently suggest replacing any of these tools,
-although implementing it effectively may require modifications to some or
-all of them.
+This proposal suggests replacing the use of Rietveld for code review with
+the more full-featured Kallithea-based forge.python.org service proposed in
+PEP 474. Guido has indicated that the original Rietveld implementation was
+primarily intended as a public demonstration application for Google App
+Engine, and switching to Kallithea will address some of the issues with
+identifying intended target branches that arise when working with patch files
+on Roundup and the associated reviews in the integrated Rietveld instance.
 
-It does however suggest the addition of new tools in order to automate
-additional parts of the workflow, as well as a critical review of these
-tools to see which, if any, may be candidates for replacement.
+It also suggests the addition of new tools in order to automate
+additional parts of the workflow, as well as a critical review of the
+remaining tools to see which, if any, may be candidates for replacement.
 
 
 Proposal
@@ -224,12 +230,12 @@
 the queue, and rebuilds the queue without the failing patch.
 
 If a developer looks at a test which failed on merge and determines that it
-was due to an intermittent failure, then they can resubmit the patch for
+was due to an intermittent failure, they can then resubmit the patch for
 another attempt at merging.
 
 To adapt this process to CPython, it should be feasible to have Zuul monitor
-Rietveld for approved patches (which would require a feature addition in
-Rietveld), submit them to Buildbot for testing on the stable buildbots, and
+Kallithea for approved pull requests (which may require a feature addition in
+Kallithea), submit them to Buildbot for testing on the stable buildbots, and
 then merge the changes appropriately in Mercurial. This idea poses a few
 technical challenges, which have their own section below.
 
@@ -280,7 +286,7 @@
 still allowing the rest of the automation flows to be worked out (such as
 how to push a patch into the merge queue).
 
-The one downside to this approach is that Zuul wouldn't have complete
+The key downside to this approach is that Zuul wouldn't have complete
 control of the merge process as it usually expects, so there would
 potentially be additional coordination needed around that.
 
@@ -288,14 +294,15 @@
 deployment proves to have more trouble with test reliability than is
 anticipated.
 
-It would also be possible to tweak the merge gating criteria such that it doesn't
-run the test suite if it detects that the patch hasn't modified any files
-outside the "Docs" tree, and instead only checks that the documentation
+It would also be possible to tweak the merge gating criteria such that it
+doesn't run the test suite if it detects that the patch hasn't modified any
+files outside the "Docs" tree, and instead only checks that the documentation
 builds without errors.
 
 As yet another alternative, it may be reasonable to move some parts of the
-documentation (such as the tutorial) out of the main source repository and
-manage them using the simpler pull request based model.
+documentation (such as the tutorial and the HOWTO guides) out of the main
+source repository and manage them using the simpler pull request based model
+described in PEP 474.
 
 
 Perceived Benefits
@@ -346,10 +353,11 @@
 Finally, a more stable default branch in CPython makes it easier for
 other Python projects to conduct continuous integration directly against the
 main repo, rather than having to wait until we get into the release
-candidate phase. At the moment, setting up such a system isn't particularly
-attractive, as it would need to include an additional mechanism to wait
-until CPython's own Buildbot fleet had indicate that the build was in a
-usable state.
+candidate phase of a new release. At the moment, setting up such a system
+isn't particularly attractive, as it would need to include an additional
+mechanism to wait until CPython's own Buildbot fleet indicated that the
+build was in a usable state. With the proposed merge gating system, the
+trunk always remains usable.
 
 
 Technical Challenges
@@ -361,20 +369,17 @@
 in some of our existing tools.
 
 
-Rietveld/Roundup vs Gerrit
---------------------------
+Kallithea vs Gerrit
+-------------------
 
-Rietveld does not currently include a voting/approval feature that is
+Kallithea does not currently include a voting/approval feature that is
 equivalent to Gerrit's. For CPython, we wouldn't need anything as
 sophisticated as Gerrit's voting system - a simple core-developer-only
 "Approved" marker to trigger action from Zuul should suffice. The
 core-developer-or-not flag is available in Roundup, as is the flag
 indicating whether or not the uploader of a patch has signed a PSF
-Contributor Licensing Agreement, which may require further additions to
-the existing integration between the two tools.
-
-Rietveld may also require some changes to allow the uploader of a patch
-to indicate which branch it is intended for.
+Contributor Licensing Agreement, which may require further development to
+link contributor accounts between the Kallithea instance and Roundup.
 
 We would likely also want to improve the existing patch handling,
 in particular looking at how the Roundup/Reitveld integration handles cases
@@ -386,29 +391,33 @@
 Some of the existing Zuul triggers work by monitoring for particular comments
 (in particular, recheck/reverify comments to ask Zuul to try merging a
 change again if it was previously rejected due to an unrelated intermittent
-failure). We will likely also want similar explicit triggers for Rietveld.
+failure). We will likely also want similar explicit triggers for Kallithea.
 
 The current Zuul plugins for Gerrit work by monitoring the Gerrit activity
-stream for particular events. If Rietveld has no equivalent, we will need
+stream for particular events. If Kallithea has no equivalent, we will need
 to add something suitable for the events we would like to trigger on.
 
 There would also be development effort needed to create a Zuul plugin
-that monitors Rietveld activity rather than Gerrit.
+that monitors Kallithea activity rather than Gerrit.
 
 
 Mercurial vs Gerrit/git
 -----------------------
 
 Gerrit uses git as the actual storage mechanism for patches, and
-automatically handles merging of approved patches. By contrast, Rietveld
-works directly on patches, and is completely decoupled from any specific
-version control system.
+automatically handles merging of approved patches. By contrast, Kallithea
+use the RhodeCode created `vcs <https://pythonhosted.org/vcs/>` library as
+an abstraction layer over specific DVCS implementations (with Mercurial and
+git backends currently available).
 
 Zuul is also directly integrated with git for patch manipulation - as far
-as I am aware, this part of the design isn't pluggable. However, at PyCon
-US 2014, the Mercurial core developers at the sprints expressed some
-interest in collaborating with the core development team and the Zuul
+as I am aware, this part of the design currently isn't pluggable. However,
+at PyCon US 2014, the Mercurial core developers at the sprints expressed
+some interest in collaborating with the core development team and the Zuul
 developers on enabling the use of Zuul with Mercurial in addition to git.
+As Zuul is itself a Python application, migrating it to use the same DVCS
+abstraction library as RhodeCode and Kallithea may be a viable path towards
+achieving that.
 
 
 Buildbot vs Jenkins
@@ -463,27 +472,28 @@
 maintenance branches.
 
 Python 2.7 can be handled easily enough by treating it as a separate patch
-queue. This would just require a change in Rietveld to indicate which
-branch was the intended target of the patch.
+queue. This would be handled natively in Kallithea by submitting separate
+pull requests in order to update the Python 2.7 maintenance branch.
 
 The Python 3.x maintenance branches are potentially more complicated. My
 current recommendation is to simply stop using Mercurial merges to manage
 them, and instead treat them as independent heads, similar to the Python
-2.7 branch. Patches that apply cleanly to both the active maintenance branch
-and to default would then just be submitted to both queues, while other
-changes might involve submitting separate patches for the active maintenance
-branch and for default. This approach also has the benefit of adjusting
-cleanly to the intermittent periods where we have two active Python 3
-maintenance branches.
+2.7 branch. Separate pull requests would need to be submitted for the active
+Python 3 maintenance branch and the default development branch. The
+downside of this approach is that it increases the risk that a fix is merged
+only to the maintenance branch without also being submitted to the default
+branch, so we may want to design some additional tooling that ensures that
+every maintenance branch pull request either has a corresponding default
+branch pull request prior to being merged, or else has an explicit disclaimer
+indicating that it is only applicable to that branch and doesn't need to be
+ported forward to later branches.
 
-This does suggest some user interface ideas for the branch nomination
-interface for a patch:
+Such an approach has the benefit of adjusting relatively cleanly to the
+intermittent periods where we have two active Python 3 maintenance branches.
 
-* default to "default" on issues that are marked as "enhancement"
-* default to "3.x+" (where 3.x is the oldest branch in regular maintenance)
-  on any other issues
-* also offer the ability to select specific branches in addition to or
-  instead of the default selection
+This issue does suggest some potential user interface ideas for Kallithea,
+where it may be desirable to be able to clone a pull request in order to be
+able to apply it to a second branch.
 
 
 Handling of security branches
@@ -491,7 +501,10 @@
 
 For simplicity's sake, I would suggest leaving the handling of
 security-fix only branches alone: the release managers for those branches
-would continue to backport specific changes manually.
+would continue to backport specific changes manually. The only change is
+that they would be able to use the Kallithea pull request workflow to do the
+backports if they would like others to review the updates prior to merging
+them.
 
 
 Handling of NEWS file updates
@@ -510,9 +523,9 @@
 -------------------------------------
 
 Instability of the nominally stable buildbots has a substantially larger
-impact under this proposal. We would need to ensure we're happy with each
-of those systems gating merges to the development branches, or else move
-then to "unstable" status.
+impact under this proposal. We would need to ensure we're genuinely happy
+with each of those systems gating merges to the development branches, or
+else move then to "unstable" status.
 
 
 Intermittent test failures
@@ -535,29 +548,20 @@
 hence likely even more amenable to automated analysis.
 
 
-Enhancing Mercurial/Rietveld/Roundup integration
-------------------------------------------------
+Custom Mercurial client workflow support
+----------------------------------------
 
 One useful part of the OpenStack workflow is the "git review" plugin,
 which makes it relatively easy to push a branch from a local git clone up
 to Gerrit for review.
 
-It seems that it should be possible to create a plugin that similarly
-integrates Mercurial queues with Rietveld and Roundup, allowing a draft
-patch to be uploaded as easily as running a command like "hg qpost" with a
-suitable .hgqpost configuration file checked in to the source repo.
+PEP 474 mentions a draft `custom Mercurial
+extension <https://bitbucket.org/ncoghlan/cpydev/src/default/cpyhg.py?at=default>`__
+that automates some aspects of the existing CPython core development workflow.
 
-(There's an existing `hg review <http://sjl.bitbucket.org/hg-review/>`__,
-plugin hence the suggestion of ``hg qpost`` as an alternate command)
-
-It would also be good to work directly with the Mercurial folks to come up
-with a tailored CPython-specific tutorial for using Mercurial queues and
-other extensions to work effectively with the CPython repository structure.
-We have some of that already in the developer guide, but I've come to believe
-that we may want to start getting more opinionated as to which extensions
-we recommend using, especially for users that have previously learned
-``git`` and need to know which extensions to enable to gain a similar level
-of flexibility in their local workflow from Mercurial.
+As part of this proposal, that custom extension would be extended to work
+with the new Kallithea based review workflow in addition to the legacy
+Roundup/Rietveld based review workflow.
 
 
 Social Challenges
@@ -604,9 +608,9 @@
 <https://wiki.python.org/moin/CallForTrackers>`__ rather than in a PEP).
 
 Accordingly, proposals that involve setting ourselves up for "SourceForge
-usability and reliability issues, round two" aren't likely to gain any
-traction with either the CPython core development team or with the PSF
-Infrastructure committee. This proposal respects that history by
+usability and reliability issues, round two" will face significant
+opposition from at least some members of the CPython core development team
+(including the author of this PEP). This proposal respects that history by
 recommending only tools that are available for self-hosting as sponsored
 or PSF funded infrastructure, and are also open source Python projects that
 can be customised to meet the needs of the CPython core development team.
@@ -665,8 +669,9 @@
 ==============
 
 Pretty much everything in the PEP. Do we want to adopt merge gating and
-Zuul? Is Rietveld the right place to hook Zuul into our current workflows?
-How do we want to address the various technical challenges?
+Zuul? How do we want to address the various technical challenges?
+Are the Kallithea and Zuul development communities open to the kind
+of collaboration that would be needed to make this effort a success?
 
 Assuming we do want to do it (or something like it), how is the work going
 to get done? Do we try to get it done solely as a volunteer effort? Do we
@@ -678,14 +683,18 @@
 OpenStack infrastructure team, and the available development resources for
 OpenStack currently dwarf those for CPython?
 
+Do those of us working for Python redistributors and major users (including
+me), attempt to make the business case to our superiors for investing
+developer time in supporting this effort?
+
 
 Next Steps
 ==========
 
-Unfortunately, we ran out of time at the PyCon 2014 language summit to really
-discuss these issues. However, the `core-workflow mailing list
-<https://mail.python.org/mailman/listinfo/core-workflow>`__ has now been set
-up to discuss workflow issues in general.
+If pursued, this will be a follow-on project to the Kallithea-based
+forge.python.org proposal in PEP 474. Refer to that PEP for more details
+on the discussion, review and proof-of-concept pilot process currently
+under way.
 
 
 Acknowledgements
@@ -696,6 +705,11 @@
 Taylor for additional technical feedback following publication of the
 initial draft.
 
+Thanks to Bradley Kuhn, Mads Kiellerich and other Kallithea developers for
+the discussions around PEP 474 that led to a significant revision of this
+proposal to be based on using Kallithea for the review component rather than
+the existing Rietveld installation.
+
 
 Copyright
 =========
diff --git a/pep-0474.txt b/pep-0474.txt
--- a/pep-0474.txt
+++ b/pep-0474.txt
@@ -7,7 +7,7 @@
 Type: Process
 Content-Type: text/x-rst
 Created: 19-Jul-2014
-Post-History: 19-Jul-2014, 08-Jan-2015
+Post-History: 19-Jul-2014, 08-Jan-2015, 01-Feb-2015
 
 
 Abstract
@@ -287,6 +287,61 @@
 forge.python.org hosted Mercurial repositories.
 
 
+Pilot Objectives and Timeline
+=============================
+
+This proposal is part of Brett Cannon's `current evaluation
+<https://mail.python.org/pipermail/python-dev/2014-December/137472.html>`__
+of improvement proposals for various aspects of the CPython development
+workflow. Key dates in that timeline are:
+
+* Feb 1: Draft proposal published (for Kallithea, this PEP)
+* Apr 8: Discussion of final proposals at Python Language Summit
+* May 1: Brett's decision on which proposal to accept
+* Sep 13: Python 3.5 released, adopting new workflows for Python 3.6
+
+Prior to the April 8 discussion, it is proposed to have the following aspects
+of this PEP completed:
+
+* a reference implementation operational at kallithea-pilot.python.org,
+  containing at least the developer guide and PEP repositories. This will
+  be a "throwaway" instance, allowing core developers and other contributors
+  to experiement freely without worrying about the long term consequences for
+  the repository history.
+* read-only live mirrors of the Kallithea hosted repositories on GitHub and
+  BitBucket. As with the pilot service itself, these would be temporary repos,
+  to be discarded after the pilot period ends.
+* clear documentation on using those mirrors to create pull requests against
+  Kallithea hosted Mercurial repositories (for the pilot, this will likely
+  *not* include using the native pull request workflows of those hosted
+  services)
+* automatic linking of issue references in code review comments and commit
+  messages to the corresponding issues on bugs.python.org
+* draft updates to PEP 1 explaining the Kallithea based PEP editing and
+  submission workflow
+
+The following items would be needed for a production migration, but there
+doesn't appear to be an obvious way to trial an updated implementation as
+part of the pilot:
+
+* adjusting the PEP publication process and the developer guide publication
+  process to be based on the relocated Mercurial repos
+
+The following items would be objectives of the overall workflow improvement
+process, but may not be completed before the Python Language summit, and are
+also considered "desirable, but not essential" for the initial adoption of
+the new service in September (if this proposal is the one selected):
+
+* allowing the use of python-social-auth to authenticate against the PSF
+  hosted Kallithea instance
+* allowing the use of the GitHub and BitBucket pull request workflows to
+  submit pull requests to the main Kallithea repo
+* allowing easy triggering of forced BuildBot runs based on Kallithea hosted
+  repos and pull requests (prior to the implementation of PEP 462, this
+  would be intended for use with sandbox repos rather than the main CPython
+  repo)
+
+
 Future Implications for CPython Core Development
 ================================================
 

-- 
Repository URL: https://hg.python.org/peps