[Python-checkins] peps: Various changes to PEP 512 based on feedback from core-workflow
brett.cannon
python-checkins at python.org
Mon Jan 18 13:53:01 EST 2016
https://hg.python.org/peps/rev/633f51d10a67
changeset: 6196:633f51d10a67
user: Brett Cannon <brett at python.org>
date: Mon Jan 18 10:52:57 2016 -0800
summary:
Various changes to PEP 512 based on feedback from core-workflow
files:
pep-0512.txt | 179 ++++++++++++++++++++++++--------------
1 files changed, 114 insertions(+), 65 deletions(-)
diff --git a/pep-0512.txt b/pep-0512.txt
--- a/pep-0512.txt
+++ b/pep-0512.txt
@@ -97,24 +97,24 @@
The overarching goal of this migration is to improve the development
process to the extent that a core developer can go from external
contribution submission through all the steps leading to committing
-said contribution all from within a browser on a tablet with WiFi.
-All of this will be done in such a way that if an external
-contributor chooses not to use GitHub then they will continue to have
-that option.
+said contribution all from within a browser on a tablet with WiFi
+using *some* development process (this does not inherently mean
+GitHub's default workflow). All of this will be done in such a way
+that if an external contributor chooses not to use GitHub then they
+will continue to have that option.
Repositories to Migrate
=======================
While hg.python.org [#h.p.o]_ hosts many repositories, there are only
-six key repositories that must move:
+five key repositories that should move:
1. devinabox [#devinabox-repo]_
2. benchmarks [#benchmarks-repo]_
-3. tracker [#tracker-repo]_
4. peps [#peps-repo]_
5. devguide [#devguide-repo]_
6. cpython [#cpython-repo]_
-The devinabox, benchmarksm and tracker repositories are code-only.
+The devinabox and benchmarks repositories are code-only.
The peps and devguide repositories involve the generation of webpages.
And the cpython repository has special requirements for integration
with bugs.python.org [#b.p.o]_.
@@ -131,11 +131,10 @@
Requirements for Code-Only Repositories
---------------------------------------
Completion of the requirements in this section will allow the
-devinabox, benchmarks, and tracker repositories to move to
+devinabox and benchmarks repositories to move to
GitHub. While devinabox has a sufficiently descriptive name, the
benchmarks repository does not; therefore, it will be named
-"python-benchmark-suite". The tracker repo also has a misleading name
-and will be renamed "bugs.python.org".
+"python-benchmark-suite".
Create a 'python-dev' team
''''''''''''''''''''''''''
@@ -174,6 +173,10 @@
bugs.python.org [#b.p.o]_ account and their GitHub account, which
will be done through a new field in a user's profile.
+This does implicitly require that contributors will need both a
+GitHub [#github]_ and bugs.python.org account in order to sign the
+CLA and contribute through GitHub.
+
A bot to enforce CLA signing
++++++++++++++++++++++++++++
With an association between someone's GitHub account and their
@@ -216,11 +219,14 @@
Document steps to commit a pull request
'''''''''''''''''''''''''''''''''''''''
During the process of choosing a new development workflow, it was
-decided that a linear history is desired. This means that the
-convenient "Merge" button in GitHub pull requests is undesireable, as
-it creates a merge commit along with all of the contributor's
-individual commits (this does not affect the other repositories where
-the desire for a linear history doesn't exist).
+decided that a linear history is desired. People preferred having a
+single commit representing a single change instead of having a set of
+unrelated commits lead to a merge commit that represented a single
+change. This means that the convenient "Merge" button in GitHub pull
+requests is undesirable, as it creates a merge commit along with all
+of the contributor's individual commits (this does not affect the
+other repositories where the desire for a linear history doesn't
+exist).
Luckily, Git [#git]_ does not require GitHub's workflow and so one can
be chosen which gives us a linear history by using Git's CLI. The
@@ -285,7 +291,7 @@
as there can take multiple pull requests to solve a single issue
(technically it should be a many-to-many association for when a
single fix solves multiple issues, but this is fairly rare and issues
-can be merged into one using the ``Superceder`` field on the issue
+can be merged into one using the ``Superseder`` field on the issue
tracker).
Association between a pull request and an issue will be done based on
@@ -338,6 +344,16 @@
attribute will need to be removed. An equivalent ``sys._git``
attribute will be needed to take its place.
+Update the devguide
+'''''''''''''''''''
+The devguide will need to be updated with details of the new
+workflow. Mostly likely work will take place in a separate branch
+until the migration actually occurs.
+
+Update PEP 101
+''''''''''''''
+The release process will need to be updated as necessary.
+
Optional, Planned Features
--------------------------
Once the cpython repository [#cpython-repo]_ is migrated, all
@@ -457,11 +473,24 @@
repositories to simplify their maintenance and to expand who has
commit rights to them to ease in their maintenance.
+It has also been suggested to split out the
+`What's New <https://docs.python.org/3/whatsnew/index.html>`__
+documents. That would require deciding whether a workflow could be
+developed where it would be difficult to forget to update
+What's New (potentially through a label added to PRs, like
+"What's New needed").
+
+Backup of Git repositories
+''''''''''''''''''''''''''
+While not necessary, it would be good to have official backups of the
+various Git repositories for disaster protection. It will be up to
+the PSF infrastructure committee to decide if this is worthwhile or
+unnecessary.
+
Status
======
-Requirements for migrating the devinabox [#devinabox-repo]_,
-benchmarks [#benchmarks-repo]_, and tracker [#tracker-repo]_
-repositories:
+Requirements for migrating the devinabox [#devinabox-repo]_ and
+benchmarks [#benchmarks-repo]_ repositories:
* Not started
@@ -478,63 +507,66 @@
- None
- Repositories whose build steps need updating:
+Repositories whose build steps need updating:
- * Not started
+* Not started
- - peps [#peps-repo]_
- - devguide [#devguide-repo]_
+ - peps [#peps-repo]_
+ - devguide [#devguide-repo]_
- * In progress
+* In progress
- - None
+ - None
- * Completed
+* Completed
- - None
+ - None
- Requirements to move over the cpython repo [#cpython-repo]_:
+Requirements to move over the cpython repo [#cpython-repo]_:
- * Not started
+* Not started
- - `Document steps to commit a pull request`_
- - `Handling Misc/NEWS`_
- - `Handling Misc/ACKS`_
- - `Linking a pull request to an issue`_
- - `Notify the issue if the pull request is committed`_
- - `Update linking service for mapping commit IDs to URLs`_
- - `Create https://git.python.org`_
- - `Backup of pull request data`_
- - `Change sys._mercurial`_
+ - `Document steps to commit a pull request`_
+ - `Handling Misc/NEWS`_
+ - `Handling Misc/ACKS`_
+ - `Linking a pull request to an issue`_
+ - `Notify the issue if the pull request is committed`_
+ - `Update linking service for mapping commit IDs to URLs`_
+ - `Create https://git.python.org`_
+ - `Backup of pull request data`_
+ - `Change sys._mercurial`_
+ - `Update the devguide`_
+ - `Update PEP 101`_
- * In progress
+* In progress
- - None
+ - None
- * Completed
+* Completed
- - None
+ - None
- Optional features:
+Optional features:
- * Not started
+* Not started
- - `Bot to handle pull request merging`_
- - `Continuous integration per pull request`_
- - `Test coverage report`_
- - `Notifying issues of pull request comments`_
- - `Allow bugs.python.org to use GitHub as a login provider`_
- - `Web hooks for re-generating web content`_
- - `Link web content back to files that it is generated from`_
- - `Splitting out parts of the documentation into their own repositories`_
+ - `Bot to handle pull request merging`_
+ - `Continuous integration per pull request`_
+ - `Test coverage report`_
+ - `Notifying issues of pull request comments`_
+ - `Allow bugs.python.org to use GitHub as a login provider`_
+ - `Web hooks for re-generating web content`_
+ - `Link web content back to files that it is generated from`_
+ - `Splitting out parts of the documentation into their own repositories`_
+ - `Backup of Git repositories`_
- * In progress
+* In progress
- - None
+ - None
- * Completed
+* Completed
- - None
+ - None
Open Issues
===========
@@ -556,6 +588,10 @@
time and resources to keep it running. They may also choose whether
they want to host a Git mirror on PSF infrastructure.
+Depending on the decision reached, other ancillary repositories will
+either be forced to migration or they can choose to simply stay on
+hg.python.org.
+
Tools and commands to move from Mercurial to Git
------------------------------------------------
A decision needs to be made on exactly what tooling and what commands
@@ -579,7 +615,7 @@
How to handle the Misc/NEWS file
--------------------------------
-There are two competing approaches to handling
+There are three competing approaches to handling
``Misc/NEWS`` [#news-file]_. One is to add a news entry for issues on
bugs.python.org [#b.p.o]_. This would mean an issue that is marked
as "resolved" could not be closed until a news entry is added in the
@@ -593,13 +629,13 @@
the output needed to be checked into the code repository. This
approach is agnostic to whether a commit was done by CLI or bot.
-The competing approach is to use an individual file per news entry,
-containg the text for the entry. In this scenario each feature
+A competing approach is to use an individual file per news entry,
+containing the text for the entry. In this scenario each feature
release would have its own directory for news entries and a separate
file would be created in that directory that was either named after
the issue it closed or a timestamp value (which prevents collisions).
Merges across branches would have no issue as the news entry file
-would still be uniqeuely named and in the directory of the latest
+would still be uniquely named and in the directory of the latest
version that contained the fix. A script would collect all news entry
files no matter what directory they reside in and create an
appropriate news file (the release directory can be ignored as the
@@ -618,8 +654,14 @@
flattened commit (while most likely also supporting using the first
line of the commit message if no specific news entry was specified).
Code for this approach has been written previously for the Mercurial
-workflow at http://bugs.python.org/issue18967. There is also a tool
-from the community at https://pypi.python.org/pypi/towncrier.
+workflow at http://bugs.python.org/issue18967. There is also tools
+from the community like https://pypi.python.org/pypi/towncrier and
+https://github.com/twisted/newsbuilder .
+
+A yet third option is a merge script to handle the conflicts. This
+approach allows for keeping the NEWS file as a single file. It does
+run the risk, though, of failure and thus blocking a commit until it
+can be manually resolved.
Naming the commit bot
---------------------
@@ -725,10 +767,19 @@
oldest branch first and then merged up to the default branch, the
question came up as to whether this workflow should be perpetuated.
In the end it was decided that committing in the newest branch and
-then cherrypicking changes into older branches would work best as
+then cherry-picking changes into older branches would work best as
most people will instinctively work off the newest branch and it is a
more common workflow when using Git [#git]_.
+Cherry-picking is also more bot-friendly for an in-browser workflow.
+In the merge-up scenario, if you were to request a bot to do a merge
+and it failed, then you would have to make sure to immediately solve
+the merge conflicts if you still allowed the main commit, else you
+would need to postpone the entire commit until all merges could be
+handled. With a cherry-picking workflow, the main commit could
+proceed while postponing the merge-failing cherry-picks. This allows
+for possibly distributing the work of managing conflicting merges.
+
Deriving ``Misc/NEWS`` from the commit logs
-------------------------------------------
As part of the discussion surrounding `Handling Misc/NEWS`_, the
@@ -774,8 +825,6 @@
.. [#peps-repo] Mercurial repository of the Python Enhancement Proposals (https://hg.python.org/peps/)
-.. [#tracker-repo] bugs.python.org code repository (https://hg.python.org/tracker/python-dev/)
-
.. [#devguide-repo] Mercurial repository for the Python Developer's Guide (https://hg.python.org/devguide/)
.. [#cpython-repo] Mercurial repository for CPython (https://hg.python.org/cpython/)
--
Repository URL: https://hg.python.org/peps
More information about the Python-checkins
mailing list