Various changes to PEP 512 based on feedback from core-workflow
This commit is contained in:
Brett Cannon
parent
982953cea7
commit
ee38420e88
179
pep-0512.txt
179
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.
|
||||
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 @@ 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
|
||||
and will be renamed "bugs.python.org".
|
||||
"python-benchmark-suite".
|
||||
|
||||
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
|
||||
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 @@ 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]_,
|
||||
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 @@ repositories:
|
|||
|
||||
- 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 @@ 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,
|
||||
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 @@ 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
|
||||
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 @@ 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/)
|
||||
|
|
|
|||
Loading…
Reference in New Issue