Various changes to PEP 512 based on feedback from core-workflow

pep-0512.txt

@@ -97,24 +97,24 @@ migration to GitHub [#pythocat]_.
 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.
+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
+using *some* development process (this does not inherently mean
-contributor chooses not to use GitHub then they will continue to have
+GitHub's default workflow). All of this will be done in such a way
-that option.
+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 @@ not necessarily the requirements within a section.
 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
+"python-benchmark-suite".
-and will be renamed "bugs.python.org".
 
 Create a 'python-dev' team
 ''''''''''''''''''''''''''
@@ -174,6 +173,10 @@ means is that an association will be needed between a person's
 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 @@ compared to the other repositories mentioned in this PEP.
 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
+decided that a linear history is desired. People preferred having a
-convenient "Merge" button in GitHub pull requests is undesireable, as
+single commit representing a single change instead of having a set of
-it creates a merge commit along with all of the contributor's
+unrelated commits lead to a merge commit that represented a single
-individual commits (this does not affect the other repositories where
+change. This means that the convenient "Merge" button in GitHub pull
-the desire for a linear history doesn't exist).
+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 @@ when a fix has been proposed. The association needs to be many-to-one
 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 @@ Once Python is no longer kept in Mercurial, the ``sys._mercurial``
 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 @@ These parts of the documentation could be broken out into their own
 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]_,
+Requirements for migrating the devinabox [#devinabox-repo]_ and
-benchmarks [#benchmarks-repo]_, and tracker [#tracker-repo]_
+benchmarks [#benchmarks-repo]_ repositories:
-repositories:
 
 * Not started
 
@@ -478,63 +507,66 @@ repositories:
 
   - None
 
- Repositories whose build steps need updating:
+Repositories whose build steps need updating:
 
- * Not started
+* Not started
 
-   - peps [#peps-repo]_
+  - peps [#peps-repo]_
-   - devguide [#devguide-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`_
+  - `Document steps to commit a pull request`_
-   - `Handling Misc/NEWS`_
+  - `Handling Misc/NEWS`_
-   - `Handling Misc/ACKS`_
+  - `Handling Misc/ACKS`_
-   - `Linking a pull request to an issue`_
+  - `Linking a pull request to an issue`_
-   - `Notify the issue if the pull request is committed`_
+  - `Notify the issue if the pull request is committed`_
-   - `Update linking service for mapping commit IDs to URLs`_
+  - `Update linking service for mapping commit IDs to URLs`_
-   - `Create https://git.python.org`_
+  - `Create https://git.python.org`_
-   - `Backup of pull request data`_
+  - `Backup of pull request data`_
-   - `Change sys._mercurial`_
+  - `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`_
+  - `Bot to handle pull request merging`_
-   - `Continuous integration per pull request`_
+  - `Continuous integration per pull request`_
-   - `Test coverage report`_
+  - `Test coverage report`_
-   - `Notifying issues of pull request comments`_
+  - `Notifying issues of pull request comments`_
-   - `Allow bugs.python.org to use GitHub as a login provider`_
+  - `Allow bugs.python.org to use GitHub as a login provider`_
-   - `Web hooks for re-generating web content`_
+  - `Web hooks for re-generating web content`_
-   - `Link web content back to files that it is generated from`_
+  - `Link web content back to files that it is generated from`_
-   - `Splitting out parts of the documentation into their own repositories`_
+  - `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 @@ PSF infrastructure committee to decide if they want to spend the
 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 @@ keep/add attribution.
 
 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 @@ bugs.python.org for relevant new entries for a release and to produce
 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,
+A competing approach is to use an individual file per news entry,
-containg the text for the entry. In this scenario each feature
+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 @@ specify a specific news entry and create the file as part of its
 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
+workflow at http://bugs.python.org/issue18967. There is also tools
-from the community at https://pypi.python.org/pypi/towncrier.
+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 @@ As the current development process has changes committed in the
 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 @@ References
 
 .. [#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/)