From 0ad84cdd913dfd58df1fe4862eb7bf06cc8f4882 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 16 Oct 2024 20:55:04 -0400 Subject: [PATCH] More uniform terminology: patch and changeset #1443 (#1446) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Ezio Melotti --- contrib/code/index.rst | 2 +- core-developers/become-core-developer.rst | 2 +- core-developers/committing.rst | 12 ++++++------ core-developers/motivations.rst | 6 +++--- core-developers/responsibilities.rst | 6 +++--- developer-workflow/development-cycle.rst | 6 +++--- developer-workflow/psrt.rst | 14 +++++++------- developer-workflow/stdlib.rst | 6 +++--- getting-started/fixing-issues.rst | 6 +++--- getting-started/git-boot-camp.rst | 8 ++++---- getting-started/pull-request-lifecycle.rst | 10 +++++----- getting-started/setup-building.rst | 4 ++-- index.rst | 2 +- testing/buildbots.rst | 10 +++++----- triage/triaging.rst | 2 +- 15 files changed, 48 insertions(+), 48 deletions(-) diff --git a/contrib/code/index.rst b/contrib/code/index.rst index 6c23c3a87a..e7969406fa 100644 --- a/contrib/code/index.rst +++ b/contrib/code/index.rst @@ -9,7 +9,7 @@ Code contributions |purpose| * Code setup and building (more complex stuff, delta from basic setup above) -* More git bootcamp (patches, etc) +* More Git bootcamp (pull requests, etc) * Lifecycle of a code pull request * Development workflow (from devguide) * Testing and buildbots (from devguide) diff --git a/core-developers/become-core-developer.rst b/core-developers/become-core-developer.rst index a9460b3779..40cedeb51d 100644 --- a/core-developers/become-core-developer.rst +++ b/core-developers/become-core-developer.rst @@ -8,7 +8,7 @@ How to become a core developer What it takes ============= -When you have consistently contributed patches which meet quality standards +When you have consistently made contributions which meet quality standards without requiring extensive rewrites prior to being committed, you may qualify for commit privileges and become a core developer of Python. You must also work well with other core developers (and people in general) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index cf859ab9f7..326578c0b3 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -31,11 +31,11 @@ to enter the public source tree. Ask yourself the following questions: * **Do the checks on the pull request show that the test suite passes?** Make sure that all of the status checks are passing. -* **Is the patch in a good state?** - Check :ref:`patch` and :ref:`helptriage` to review what is expected of - a patch. +* **Is the pull request in a good state?** + Check :ref:`pull-request-lifecycle` and :ref:`helptriage` to review what + is expected of a pull request. -* **Does the patch break backwards-compatibility without a strong reason?** +* **Does the change break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the semantics, then there needs to be a strong reason, because it will cause some peoples' code to break. @@ -165,7 +165,7 @@ number since it is part of the file name. You can use entry:: Fix warning message when :func:`os.chdir` fails inside - :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. + :func:`test.support.temp_cwd`. Contributed by Chris Jerdonek. The inline Sphinx roles like ``:func:`` can be used help readers find more information. You can build HTML and verify that the @@ -182,7 +182,7 @@ As a core developer, you have the ability to push changes to the official Python repositories, so you need to be careful with your workflow: * **You should not push new branches to the main repository.** You can - still use them in the fork that you use for the development of patches. + still use them in the fork that you use for your own development. You can also push these branches to a separate public repository for maintenance work before it is integrated into the main repository. diff --git a/core-developers/motivations.rst b/core-developers/motivations.rst index b805a7c67f..24f1ad2c89 100644 --- a/core-developers/motivations.rst +++ b/core-developers/motivations.rst @@ -279,11 +279,11 @@ Goals of this page The `issue metrics`_ automatically collected by the CPython issue tracker strongly suggest that the current core development process is bottlenecked on -core developer time - this is most clearly indicated in the first metrics graph, -which shows both the number of open issues and the number of patches awaiting +core developer time. This is most clearly indicated in the first metrics graph, +which shows both the number of open issues and the number of pull requests awaiting review growing steadily over time, despite CPython being one of the most active open source projects in the world. This bottleneck then impacts not only -resolving open issues and applying submitted patches, but also the process of +resolving open issues and accepting submitted pull requests, but also the process of identifying, nominating and mentoring new core developers. The core commit statistics monitored by sites like `OpenHub`_ provide a good diff --git a/core-developers/responsibilities.rst b/core-developers/responsibilities.rst index 1ea1a09947..5cd5ed7bdb 100644 --- a/core-developers/responsibilities.rst +++ b/core-developers/responsibilities.rst @@ -7,8 +7,8 @@ Responsibilities As contributors to the CPython project, our shared responsibility is to collaborate constructively with other contributors, including core developers. This responsibility covers all forms of contribution, whether that's submitting -patches to the implementation or documentation, reviewing other peoples' -patches, triaging issues on the issue tracker, or discussing design and +pull requests to the implementation or documentation, reviewing other peoples' +pull requests, triaging issues on the issue tracker, or discussing design and development ideas on the core :ref:`communication channels `. @@ -68,7 +68,7 @@ the ability to license your code means it can be put under the PSF license so it can be legally distributed with Python. This is a very important step! Hopefully you have already submitted a -contributor agreement if you have been submitting patches. But if you have not +contributor agreement if you have been submitting pull requests. But if you have not done this yet, it is best to do this ASAP, probably before you even do your first commit so as to not forget. Also do not forget to enter your GitHub username into your details on the issue tracker. diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index c7cf6a8b2b..6d5b04a2ae 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -118,7 +118,7 @@ Commits to security branches are to be coordinated with the release manager for the corresponding feature version, as listed in the :ref:`branchstatus`. Merging of pull requests to security branches is restricted to release managers. Any release made from a security branch is source-only and done only when actual -security patches have been applied to the branch. These releases have a +security fixes have been applied to the branch. These releases have a **micro version** number greater than the last **bugfix** release. .. _eolbranch: @@ -151,8 +151,8 @@ Pre-alpha The branch is in this stage when no official release has been done since the latest final release. There are no special restrictions placed on -commits, although the usual advice applies (getting patches reviewed, avoiding -breaking the buildbots). +commits, although the usual advice applies (getting pull requests reviewed, +avoiding breaking the buildbots). .. _alpha: diff --git a/developer-workflow/psrt.rst b/developer-workflow/psrt.rst index 9347a9a81f..f469f68d12 100644 --- a/developer-workflow/psrt.rst +++ b/developer-workflow/psrt.rst @@ -68,24 +68,24 @@ severity, advisory text, and fixes. * Affected components and APIs. The module, function, class, or method must be specified so users can search their codebase for usage. For issues affecting the entire project, this can be omitted. - * Mitigations for the vulnerability beyond upgrading to a patched version, if applicable. + * Mitigations for the vulnerability beyond upgrading to a fixed version, if applicable. This can all be done within the GitHub Security Advisory UI for easier collaboration between reporter and coordinator. -* The coordinator determines the fix approach and who will provide a patch. - Some reporters are willing to provide or collaborate to create a patch, +* The coordinator determines the fix approach and who will provide a fix. + Some reporters are willing to provide or collaborate to create a fix, otherwise relevant core developers can be invited to collaborate by the coordinator. * For **Low** and **Medium** severity vulnerabilities it is acceptable - to develop a patch in public. + to develop a fix in public. The pull request must be marked with the ``security`` and ``release-blocker`` - labels so that a release is not created without including the patch. + labels so that a release is not created without including the fix. - * For **High** and **Critical** severity vulnerabilities the patch must be + * For **High** and **Critical** severity vulnerabilities the fix must be developed privately using GitHub Security Advisories' "Private Forks" feature. Core developers can be added to the GitHub Security Advisory via "collaborators" - to work on the fix together. Once a patch is approved privately and tested, + to work on the fix together. Once a fix is approved privately and tested, a public issue and pull request can be created with the ``security`` and ``release-blocker`` labels. diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index 732ee8f458..1e841d8b2e 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -36,7 +36,7 @@ You have a several options for this: If you have found general acceptance and usefulness for your code from people, you can open an issue on the `issue tracker`_ with the code attached as a -:ref:`pull request `. If possible, also submit a +:ref:`pull request `. If possible, also submit a :ref:`contributor agreement `. If a core developer decides that your code would be useful to the general @@ -91,7 +91,7 @@ In order for a module to even be considered for inclusion into the stdlib, a couple of requirements must be met. The most basic is that the code must meet -:ref:`standard patch requirements `. For code that has +:ref:`standard pull request requirements `. For code that has been developed outside the stdlib typically this means making sure the coding style guides are followed and that the proper tests have been written. @@ -112,7 +112,7 @@ infrastructure (that is, the module is no longer directly maintained outside of Python). This prevents a divergence between the code that is included in the stdlib and that which is released outside the stdlib (typically done to provide the module to older versions of Python). It also removes the burden of forcing -core developers to have to redirect bug reports or patches to an external issue +core developers to have to redirect bug reports or changes to an external issue tracker and :abbr:`VCS (version control system)`. Someone involved with the development of the diff --git a/getting-started/fixing-issues.rst b/getting-started/fixing-issues.rst index 6b752d79d9..f277cbf60d 100644 --- a/getting-started/fixing-issues.rst +++ b/getting-started/fixing-issues.rst @@ -6,7 +6,7 @@ Fixing "easy" issues (and beyond) ================================= When you feel comfortable enough to want to help tackle issues by trying to -create a patch to fix an issue, you can start by looking at the `"easy" +create a pull request to fix an issue, you can start by looking at the `"easy" issues`_. These issues *should* be ones where it should take no longer than a day or weekend to fix. But because the "easy" classification is typically done at triage time it can turn out to be inaccurate, so do feel free to leave a @@ -17,8 +17,8 @@ are not considered easy and try to fix those. It must be warned, though, that it is quite possible that a bug that has been left open has been left into that state because of the difficulty compared to the benefit of the fix. It could also still be open because no consensus has been reached on how to fix the -issue (although having a patch that proposes a fix can turn the tides of the -discussion to help bring it to a close). Regardless of why the issue is open, +issue, although having a pull request that proposes a fix can turn the tides of the +discussion to help bring it to a close. Regardless of why the issue is open, you can also always provide useful comments if you do attempt a fix, successful or not. diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 15952d6bd2..87177840cb 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -132,7 +132,7 @@ Enabling ``autocrlf`` on Windows The ``autocrlf`` option will fix automatically any Windows-specific line endings. This should be enabled on Windows, since the public repository has a hook which -will reject all changesets having the wrong line endings:: +will reject all commits having the wrong line endings:: $ git config --global core.autocrlf input @@ -356,7 +356,7 @@ Scenario: the upstream CPython repository. Please do not try to solve this by creating a pull request from -``python:main`` to ``:main`` as the authors of the patches will +``python:main`` to ``:main`` as the authors of the pull requests will get notified unnecessarily. Solution:: @@ -435,8 +435,8 @@ Solution: .. _git_pr: -Downloading other's patches ---------------------------- +Checking out others' pull requests +---------------------------------- Scenario: diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index cd037789ff..5728cb9da0 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -243,8 +243,8 @@ should do to help ensure that your pull request is accepted. ``patchcheck`` ============== -``patchcheck`` is a simple automated patch checklist that guides a developer -through the common patch generation checks. To run ``patchcheck``: +``patchcheck`` is a simple automated checklist for changes in progress that +guides a developer through common checks. To run ``patchcheck``: On *Unix* (including macOS):: @@ -256,7 +256,7 @@ On *Windows* (after any successful build): .\python.bat Tools\patchcheck\patchcheck.py -The automated patch checklist runs through: +The automated checklist runs through: * Are there any whitespace problems in Python files? (using :cpy-file:`Tools/patchcheck/reindent.py`) @@ -271,10 +271,10 @@ The automated patch checklist runs through: * Has ``configure`` been regenerated, if necessary? * Has ``pyconfig.h.in`` been regenerated, if necessary? -The automated patch check doesn't actually *answer* all of these +The automated checks don't actually *answer* all of these questions. Aside from the whitespace checks, the tool is a memory aid for the various elements that can go into -making a complete patch. +making a complete pull request. .. _good-commits: diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 8c55bc625a..03b2777b8e 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -127,7 +127,7 @@ changes to Python code will be picked up by the interpreter for immediate use and testing. (If you change C code, you will need to recompile the affected files as described below.) -Patches for the documentation can be made from the same repository; see +Changes for the documentation can be made from the same repository; see :ref:`documenting`. .. _install-pre-commit: @@ -1033,7 +1033,7 @@ you'd prefer to use that directly. Create a CPython codespace -------------------------- -Here are the basic steps needed to contribute a patch using Codespaces. +Here are the basic steps needed to contribute a pull request using Codespaces. You first need to navigate to the `CPython repo `_ hosted on GitHub. diff --git a/index.rst b/index.rst index c10736a474..ec07d41f98 100644 --- a/index.rst +++ b/index.rst @@ -22,7 +22,7 @@ community that maintains Python. We welcome your contributions to Python! Quick reference --------------- -Here are the basic steps needed to get set up and contribute a patch. +Here are the basic steps needed to get set up and contribute a pull request. This is meant as a checklist, once you know the basics. For complete instructions please see the :ref:`setup guide `. diff --git a/testing/buildbots.rst b/testing/buildbots.rst index 22962faaf6..97856f7132 100644 --- a/testing/buildbots.rst +++ b/testing/buildbots.rst @@ -16,7 +16,7 @@ will schedule a new build to be run as soon as possible. The build steps run by the buildbots are the following: -* Check out the source tree for the changeset which triggered the build +* Check out the source tree for the change which triggered the build * Compile Python * Run the test suite using :ref:`strenuous settings ` * Clean up the build tree @@ -56,7 +56,7 @@ There are three ways of visualizing recent build results: * The Web interface for each branch at https://www.python.org/dev/buildbot/, where the so-called "waterfall" view presents a vertical rundown of recent builds for each builder. When interested in one build, you'll have to - click on it to know which changesets it corresponds to. Note that + click on it to know which commits it corresponds to. Note that the buildbot web pages are often slow to load, be patient. * The command-line ``bbreport.py`` client, which you can get from @@ -78,16 +78,16 @@ There are three ways of visualizing recent build results: If you like IRC, having an IRC client open to the #python-dev-notifs channel on irc.libera.chat is useful. Any time a builder changes state (last build passed and this one didn't, or vice versa), a message is posted to the channel. -Keeping an eye on the channel after pushing a changeset is a simple way to get +Keeping an eye on the channel after pushing a commits is a simple way to get notified that there is something you should look in to. Some buildbots are much faster than others. Over time, you will learn which ones produce the quickest results after a build, and which ones take the longest time. -Also, when several changesets are pushed in a quick succession in the same +Also, when several commits are pushed in a quick succession in the same branch, it often happens that a single build is scheduled for all these -changesets. +commits. Stability ========= diff --git a/triage/triaging.rst b/triage/triaging.rst index d313ef70ef..c560d8c1d5 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -92,7 +92,7 @@ you can help by making sure the pull request: * includes proper tests * includes proper documentation changes * includes a :ref:`NEWS entry ` (if needed) -* includes the author in ``Misc/ACKS``, either already or the patch adds them +* includes the author in ``Misc/ACKS``, either already or the pull request adds them * doesn't have conflicts with the ``main`` branch * :ref:`doesn't have failing CI checks `