diff --git a/core-developers/become-core-developer.rst b/core-developers/become-core-developer.rst index 9887ffcf98..296e64b0b4 100644 --- a/core-developers/become-core-developer.rst +++ b/core-developers/become-core-developer.rst @@ -2,10 +2,10 @@ .. _coredev: ============================== -How to Become a Core Developer +How to become a core developer ============================== -What it Takes +What it takes ============= When you have consistently contributed patches which meet quality standards @@ -22,7 +22,7 @@ an official offer. How core developers come to that agreement are outlined in :pep:`13`. -Gaining Commit Privileges +Gaining commit privileges ========================= After a candidate has demonstrated consistent contributions, commit privileges diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 256fda9d1c..8b3ee2b3cc 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -1,6 +1,6 @@ .. _committing: -Accepting Pull Requests +Accepting pull requests ======================= .. highlight:: none diff --git a/core-developers/developer-log.rst b/core-developers/developer-log.rst index 5a7ff01dde..665ef07003 100644 --- a/core-developers/developer-log.rst +++ b/core-developers/developer-log.rst @@ -1,7 +1,7 @@ .. _developer-log: .. _developers: -Developer Log +Developer log ============= This page lists the historical members of the Python development team. (The @@ -13,7 +13,7 @@ information.) :file: developers.csv :encoding: "utf-8" -Procedure for Granting or Dropping Access +Procedure for granting or dropping access ----------------------------------------- To be granted the ability to manage who is a committer, you must be a diff --git a/core-developers/experts.rst b/core-developers/experts.rst index b8b962f974..419efb42cb 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -1,7 +1,7 @@ .. _experts: ============= -Experts Index +Experts index ============= This document has tables that list Python Modules, Tools, Platforms and @@ -362,7 +362,7 @@ version control merwok, ezio-melotti ================== ========================================================== -Documentation Translations +Documentation translations ========================== For a list of translators, see :ref:`this table about translations `. diff --git a/core-developers/index.rst b/core-developers/index.rst index cf743c405c..2b3ac7b799 100644 --- a/core-developers/index.rst +++ b/core-developers/index.rst @@ -1,5 +1,5 @@ =============== -Core Developers +Core developers =============== .. toctree:: diff --git a/core-developers/motivations.rst b/core-developers/motivations.rst index 625c763d97..5e2a056520 100644 --- a/core-developers/motivations.rst +++ b/core-developers/motivations.rst @@ -1,7 +1,7 @@ .. _motivations: ============================ -Motivations and Affiliations +Motivations and affiliations ============================ CPython core developers participate in the core development process for a diff --git a/core-developers/responsibilities.rst b/core-developers/responsibilities.rst index aec4b98cc7..0638a967e6 100644 --- a/core-developers/responsibilities.rst +++ b/core-developers/responsibilities.rst @@ -44,7 +44,7 @@ making design and development decisions in different areas (as documented in the :ref:`experts` and :ref:`developers`). -Communication Channels and Bug Notifications +Communication channels and bug notifications ============================================ Mailing lists have generally been replaced by the @@ -59,7 +59,7 @@ follow the link and click on the :guilabel:`Watch` button to set your notificati .. _contributor_agreement: -Sign a Contributor Agreement +Sign a contributor agreement ============================ Submitting a `contributor form for Python`_ licenses any code you contribute to @@ -77,7 +77,7 @@ username into your details on the issue tracker. .. _contributor form for Python: https://www.python.org/psf/contrib/ -Pull Request merging +Pull request merging ==================== Once you have your commit privileges on GitHub you will be able to accept diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 103abe7b0a..3525cb81fc 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -58,7 +58,7 @@ When in doubt, new internal C functions should be defined in ``Include/internal`` using the ``extern`` keyword. Private names --------------- +------------- Any API named with a leading underscore is also considered internal. There is currently only one main use case for using such names rather than @@ -74,7 +74,7 @@ the :ref:`unstable-capi`: * APIs for very specialized uses like JIT compilers. -Internal API Tests +Internal API tests ------------------ C tests for the internal C API live in ``Modules/_testinternalcapi.c``. @@ -128,7 +128,7 @@ Please start a public discussion if these guidelines won't work for your API. By *return value*, we mean the value returned by the *C return statement*. -C API Tests +C API tests ----------- Tests for the public C API live in the ``_testcapi`` module. @@ -411,7 +411,7 @@ Adding a new definition to the Limited API - Add tests -- see below. -Limited API Tests +Limited API tests ----------------- Since Limited API is a subset of the C API, there's no need to test the diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 9935474263..1ff3b85cad 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -2,7 +2,7 @@ .. _communication: ============================== -Following Python's Development +Following Python's development ============================== Python's development is communicated through a myriad of ways, @@ -24,7 +24,7 @@ in return. .. _mailinglists: -Mailing Lists +Mailing lists ============= .. note:: Some mailing lists have been supplanted by categories in the @@ -95,7 +95,7 @@ It is also the designated venue for the core developer promotion votes (as the Discourse equivalent of the `python-committers`_ mailing list). Tutorials for new users -------------------------- +----------------------- To start a topic or participate in any discussions in the forum, sign up and create an account using an email address or GitHub account. You can do so by @@ -138,7 +138,7 @@ bottom progress bar to expand it. Notifications ------------- -Following categories (Category notifications) +Following categories (category notifications) ''''''''''''''''''''''''''''''''''''''''''''' Notifications can be set for individual categories and topics. To change any of these @@ -151,7 +151,7 @@ different options: Watching, Tracking, Watching First Post, Normal, and Muted. All categories are set by default in Normal mode where you will only be notified if someone mentions your @name or replies to you. -Following individual threads (Topic notifications) +Following individual threads (topic notifications) '''''''''''''''''''''''''''''''''''''''''''''''''' To follow any individual topics or threads, you can adjust your notifications @@ -239,7 +239,7 @@ that way. You can find their blogs (and various other developers who use Python) at https://planetpython.org/. -Setting Expectations for Open Source Participation +Setting expectations for open source participation ================================================== Burn-out is common in open source due to a misunderstanding of what users, contributors, @@ -247,7 +247,7 @@ and maintainers should expect from each other. Brett Cannon gave a `talk ` starts again for the next minor version. -Repository Administration +Repository administration ''''''''''''''''''''''''' The source code is currently hosted on `GitHub `_ in the `Python organization `_. -Organization Repository Policy +Organization repository policy ------------------------------ Within the `GitHub Python organization `_, @@ -254,7 +254,7 @@ specifically want to “bless” one implementation (as with e.g. `pythoncapi-compat `_). -Organization Owner Policy +Organization owner policy ------------------------- The GitHub Organization Owner role allows for full management of all aspects of @@ -281,7 +281,7 @@ Owner of the Python Organization. .. _current owners: -Current Owners +Current owners -------------- +----------------------+--------------------------------+-----------------+ @@ -307,7 +307,7 @@ mentioned to request assistance from an organization owner. .. _be performed: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permissions-for-organization-roles -Repository Administrator Role Policy +Repository administrator role policy ------------------------------------ The Administrator role on the repository allows for managing all aspects @@ -328,7 +328,7 @@ who no longer necessitate this level of access will be removed with notice. Multi-Factor Authentication must be enabled by the user in order to remain an Administrator of the repository. -Current Administrators +Current administrators ---------------------- +-------------------+----------------------------------------------------------+-----------------+ @@ -353,7 +353,7 @@ Current Administrators | Mariatta Wijaya | Maintainer of bedevere, blurb_it and miss-islington | Mariatta | +-------------------+----------------------------------------------------------+-----------------+ -Repository Release Manager Role Policy +Repository release manager role policy -------------------------------------- Release Managers for :ref:`in-development `, :ref:`maintenance diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index 3a5a759a53..0384c2b382 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -2,7 +2,7 @@ .. _extensions: ================================== -Standard Library Extension Modules +Standard library extension modules ================================== In this section, we could explain how to write a CPython extension with the C language, but the topic can take a complete book. diff --git a/developer-workflow/grammar.rst b/developer-workflow/grammar.rst index 2ba18ec225..dfb6a2f9d2 100644 --- a/developer-workflow/grammar.rst +++ b/developer-workflow/grammar.rst @@ -1,7 +1,7 @@ .. _grammar: ========================== -Changing CPython's Grammar +Changing CPython's grammar ========================== Abstract diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst index bc90a832af..23f1909c91 100644 --- a/developer-workflow/index.rst +++ b/developer-workflow/index.rst @@ -1,5 +1,5 @@ ==================== -Development Workflow +Development workflow ==================== .. toctree:: diff --git a/developer-workflow/lang-changes.rst b/developer-workflow/lang-changes.rst index 19cc42dd1a..70ecd679d9 100644 --- a/developer-workflow/lang-changes.rst +++ b/developer-workflow/lang-changes.rst @@ -1,7 +1,7 @@ .. _lang-changes: .. _langchanges: -Changing the Python Language +Changing the Python language ============================ On occasion people come up with an idea on how to change or improve Python as a programming language. This document is meant to explain exactly what changes @@ -9,7 +9,7 @@ have a reasonable chance of being considered and what the process is to propose changes to the language. -What Qualifies +What qualifies -------------- First and foremost, it must be understood that changes to the Python programming language are difficult to make. When the language changes, @@ -66,7 +66,7 @@ see `Justifying Python Language Changes`_. .. _lang-changes-pep-process: -PEP Process +PEP process ----------- Once you are certain you have a language change proposal diff --git a/developer-workflow/porting.rst b/developer-workflow/porting.rst index fc0c915179..26756bc8fb 100644 --- a/developer-workflow/porting.rst +++ b/developer-workflow/porting.rst @@ -1,7 +1,7 @@ .. _porting: ========================= -Porting to a New Platform +Porting to a new platform ========================= The first step is to familiarize yourself with the development toolchain on diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index 176c726796..9ead7d7069 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -1,7 +1,7 @@ .. _stdlib: .. _stdlibchanges: -Adding to the Stdlib +Adding to the stdlib ==================== While the stdlib contains a great amount of useful code, sometimes you want @@ -61,7 +61,7 @@ over other available solutions. All of this means that additions to the stdlib are not taken lightly. -Acceptable Types of Modules +Acceptable types of modules ''''''''''''''''''''''''''' Typically two types of modules get added to the stdlib. One type is a module which implements something that is difficult to get right. A good example of @@ -120,7 +120,7 @@ also helps to make sure that the overall design of the module continues to be uniform. -Proposal Process +Proposal process '''''''''''''''' If the module you want to propose adding to the stdlib meets the requirements, diff --git a/development-tools/clang.rst b/development-tools/clang.rst index 1f693fcae3..14040dd8bc 100644 --- a/development-tools/clang.rst +++ b/development-tools/clang.rst @@ -1,7 +1,7 @@ .. _clang: =========================== -Dynamic Analysis with Clang +Dynamic analysis with Clang =========================== .. highlight:: bash @@ -25,7 +25,7 @@ front-end provides access to LLVM's optimizer and code generator. The sanitizers - or checkers - are hooks into the code generation phase to instrument compiled code so suspicious behavior is flagged. -What are Sanitizers? +What are sanitizers? ==================== Clang sanitizers are runtime checkers used to identify suspicious and undefined @@ -52,7 +52,7 @@ the war chest to uncovering bugs and improving code quality. Clang should be used to compliment other methods, including Code Reviews, Valgrind, Coverity, etc. -Clang/LLVM Setup +Clang/LLVM setup ================ This portion of the document covers downloading, building and installing Clang @@ -62,7 +62,7 @@ compiler, the compiler front end and the compiler runtime library. In preparation you should create a scratch directory. Also ensure you are using Python 2 and not Python 3. Python 3 will cause the build to fail. -Download, Build and Install +Download, build and install --------------------------- Perform the following to download, build and install the Clang/LLVM 3.4. :: @@ -148,7 +148,7 @@ example, you might want to run a ``scan-build`` or examine the results with things work as expected. If a library is missing, then you should search for it in the Clang/LLVM build directory. -Python Build Setup +Python build setup ================== This portion of the document covers invoking Clang and LLVM with the options @@ -306,7 +306,7 @@ compile (formatting added for clarity): If its not installed, then look in the Clang/LLVM build directory for it and copy it to ``/usr/local/bin``. -Blacklisting (Ignoring) Findings +Blacklisting (ignoring) findings -------------------------------- .. highlight:: none diff --git a/development-tools/index.rst b/development-tools/index.rst index 6a3e7466e9..d8e8453cf1 100644 --- a/development-tools/index.rst +++ b/development-tools/index.rst @@ -1,5 +1,5 @@ ================= -Development Tools +Development tools ================= .. toctree:: diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 86652ffd3b..137827b3ec 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -2,7 +2,7 @@ .. _docquality: ========================== -Helping with Documentation +Helping with documentation ========================== Python is known for having well-written documentation. Maintaining the @@ -20,7 +20,7 @@ You will find extensive and detailed information on how to write documentation and submit changes on the :ref:`Documenting Python ` page. -Python Documentation +Python documentation ==================== The :ref:`Documenting Python ` section covers the details of how diff --git a/documentation/markup.rst b/documentation/markup.rst index 8859ab8d00..0a0d51a634 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -1,7 +1,7 @@ .. _markup: ======================= -reStructuredText Markup +reStructuredText markup ======================= .. highlight:: rest @@ -10,7 +10,7 @@ This document describes the custom reStructuredText markup introduced by Sphinx to support Python documentation and how it should be used. -Quick Reference +Quick reference =============== This table summarizes which markup should be used for some commonly used @@ -38,7 +38,7 @@ comments ``.. a comment`` :ref:`commen .. _rst-primer: -reStructuredText Primer +reStructuredText primer ======================= This section is a brief introduction to reStructuredText (reST) concepts and @@ -89,7 +89,7 @@ provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is ``:rolename:`content```. -Lists and Quotes +Lists and quotes ---------------- List markup is natural: just place an asterisk at the start of a paragraph and @@ -133,7 +133,7 @@ Paragraphs are quoted by just indenting them more than the surrounding paragraphs. -Source Code +Source code ----------- Literal code blocks are introduced by ending a paragraph with the special marker @@ -200,7 +200,7 @@ Python documentation, here is a suggested convention: * ``"``, for paragraphs -Explicit Markup +Explicit markup --------------- "Explicit markup" is used in reST for most constructs that need special @@ -291,7 +291,7 @@ There are some problems one commonly runs into while authoring reST documents: .. _additional-markup-constructs: -Additional Markup Constructs +Additional markup constructs ============================ Sphinx adds a lot of new directives and interpreted text roles to standard reST diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 592059bf7f..ea72704f17 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -2,7 +2,7 @@ .. _documenting: =============== -Getting Started +Getting started =============== .. highlight:: rest @@ -169,13 +169,13 @@ replace ``html`` above with the desired builder ``name``. .. _venv-create: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment -Style Guide +Style guide =========== -Moved to :doc:`style-guide` +Moved to :doc:`style-guide`. Translating =========== -Moved to :doc:`translating` +Moved to :doc:`translating`. diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index f5dfe45704..396fe1d993 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -1,7 +1,7 @@ .. _style-guide: =========== -Style Guide +Style guide =========== .. highlight:: rest @@ -102,7 +102,7 @@ Unix The name of the operating system developed at AT&T Bell Labs in the early 1970s. -Affirmative Tone +Affirmative tone ================ The documentation focuses on affirmatively stating what the language does and @@ -127,7 +127,7 @@ language): achieve the same effect. This assures that files are flushed and file descriptor resources are released in a timely manner. -Economy of Expression +Economy of expression ===================== More documentation is not necessarily better documentation. Err on the side @@ -138,7 +138,7 @@ to understanding and can result in even more ways to misread or misinterpret the text. Long descriptions full of corner cases and caveats can create the impression that a function is more complex or harder to use than it actually is. -Security Considerations (and Other Concerns) +Security considerations (and other concerns) ============================================ Some modules provided with Python are inherently exposed to security issues @@ -159,7 +159,7 @@ module (e.g. OS level pipe buffers filling up and stalling child processes), these can be documented in a "Common Errors" section and cross-referenced rather than repeated for every affected interface. -Code Examples +Code examples ============= Short code examples can be a useful adjunct to understanding. Readers can often @@ -177,7 +177,7 @@ lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations. -Code Equivalents +Code equivalents ================ Giving pure Python code equivalents (or approximate equivalents) can be a useful diff --git a/getting-started/fixing-issues.rst b/getting-started/fixing-issues.rst index 70d33dd77f..6161f4aa60 100644 --- a/getting-started/fixing-issues.rst +++ b/getting-started/fixing-issues.rst @@ -2,7 +2,7 @@ .. _fixingissues: ================================= -Fixing "easy" Issues (and Beyond) +Fixing "easy" issues (and beyond) ================================= When you feel comfortable enough to want to help tackle issues by trying to diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index dce04a570e..d1b48f23f5 100644 --- a/getting-started/getting-help.rst +++ b/getting-started/getting-help.rst @@ -1,7 +1,7 @@ .. _getting-help: .. _help: -Where to Get Help +Where to get help ================= If you are working on Python it is very possible you will come across an issue @@ -39,7 +39,7 @@ Those particularly relevant for help contributing to Python itself include: .. _help-mailing-lists: -Mailing Lists +Mailing lists ------------- Further options for seeking assistance include the @@ -73,7 +73,7 @@ whereas ``#python`` is for questions concerning development *with* Python. .. _Libera.Chat: https://libera.chat/ -Core Mentorship +Core mentorship --------------- If you are interested in improving Python and contributing to its development, @@ -88,7 +88,7 @@ welcomed and encouraged to contribute. .. _office hour: -Core Developers Office Hours +Core developers office hours ---------------------------- Several core developers have set aside time to host mentorship office hours. @@ -105,7 +105,7 @@ during office hours. | Zachary Ware | See details link | Schedule at https://calendly.com/zware | +------------------+-------------------------------+------------------------------------------------+ -File a Bug +File a bug ---------- If you strongly suspect you have stumbled on a bug (be it in the build diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 082232cee7..ca03f69644 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -1,7 +1,7 @@ .. _git-boot-camp: .. _gitbootcamp: -Git Bootcamp and Cheat Sheet +Git bootcamp and cheat sheet ============================ .. highlight:: console @@ -29,7 +29,7 @@ relevant to CPython's workflow. .. _fork-cpython: -Forking CPython GitHub Repository +Forking CPython GitHub repository --------------------------------- You will only need to do this once. @@ -44,7 +44,7 @@ You will only need to do this once. .. _clone-your-fork: -Cloning a Forked CPython Repository +Cloning a forked CPython repository ----------------------------------- You will only need to do this once per machine. From your command line:: @@ -58,7 +58,7 @@ It is also recommended to configure an ``upstream`` remote repository:: You can also use SSH-based or HTTPS-based URLs. -Configure the Remotes +Configure the remotes --------------------- .. These steps are duplicated in setup-building in step 6 and 7. @@ -73,7 +73,7 @@ Since one should never attempt to push to ``upstream``, configure git remote set-url --push upstream git@github.com:/cpython.git -Listing the Remote Repositories +Listing the remote repositories ------------------------------- To list the remote repositories that are configured, along with their URLs:: @@ -98,7 +98,7 @@ It should emit ``upstream``, indicating to track/pull changes for ``main`` from .. _set-up-name-email: -Setting Up Your Name and Email Address +Setting up your name and email address -------------------------------------- .. code-block:: bash @@ -120,7 +120,7 @@ will reject all changesets having the wrong line endings:: git config --global core.autocrlf input -Creating and Switching Branches +Creating and switching branches ------------------------------- .. important:: @@ -159,7 +159,7 @@ on the 2.7 release from the ``upstream`` remote:: .. _deleting_branches: -Deleting Branches +Deleting branches ----------------- To delete a **local** branch that you no longer need:: @@ -174,7 +174,7 @@ To delete a **remote** branch:: You may specify more than one branch for deletion. -Renaming Branch +Renaming branch --------------- The CPython repository's default branch was renamed from ``master`` to @@ -209,7 +209,7 @@ rename your local branch as follows:: .. _commit-changes: -Staging and Committing Files +Staging and committing files ---------------------------- 1. To show the current changes:: @@ -227,7 +227,7 @@ Staging and Committing Files git commit -m "This is the commit message." -Reverting Changes +Reverting changes ----------------- To revert changes to a file that has not been committed yet:: @@ -239,7 +239,7 @@ the origin is at:: git reset --hard HEAD -Stashing Changes +Stashing changes ---------------- To stash away changes that are not ready to be committed yet:: @@ -252,7 +252,7 @@ To re-apply the last stashed change:: .. _diff-changes: -Comparing Changes +Comparing changes ----------------- View all non-commited changes:: @@ -278,7 +278,7 @@ defined in :cpy-file:`.gitattributes`, found in the repository root. .. _push-changes: -Pushing Changes +Pushing changes --------------- Once your changes are ready for a review or a pull request, you will need to push @@ -289,7 +289,7 @@ them to the remote repository. git switch git push origin -Creating a Pull Request +Creating a pull request ----------------------- 1. Go to https://github.com/python/cpython. @@ -308,7 +308,7 @@ Creating a Pull Request You should include the issue number in the title of the PR, in the format ``gh-NNNNN: ``. -Linking to Issues and Pull Requests +Linking to issues and pull requests ----------------------------------- You can link to issues and pull requests using ``gh-NNNNN`` (this form is @@ -327,7 +327,7 @@ you know for sure that a single PR is enough to address and close the issue. .. _bedevere: https://github.com/python/bedevere .. _special keywords: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword -Updating your CPython Fork +Updating your CPython fork -------------------------- Scenario: @@ -378,7 +378,7 @@ When it happens, you need to resolve conflict. See these articles about resolvi .. _git_from_patch: -Applying a Patch to Git +Applying a patch to Git ----------------------- Scenario: @@ -421,7 +421,7 @@ Solution: .. _git_pr: -Downloading Other's Patches +Downloading other's patches --------------------------- Scenario: @@ -457,7 +457,7 @@ local copy of a pull request as follows:: .. _accepting-and-merging-a-pr: -Accepting and Merging a Pull Request +Accepting and merging a pull request ------------------------------------ Pull requests can be accepted and merged by a Python Core Developer. @@ -503,7 +503,7 @@ PR life cycle, while being irrelevant to the final change. Finally, press the ``Confirm squash and merge`` button. -Cancelling an Automatic Merge +Cancelling an automatic merge ----------------------------- If you notice a problem with a pull request that was accepted and where @@ -524,7 +524,7 @@ dismissing your previous review that requested changes. Note that pushing new changes after the auto-merge flow was enabled does **NOT** stop it. -Backporting Merged Changes +Backporting merged changes -------------------------- A pull request may need to be backported into one of the maintenance branches @@ -574,7 +574,7 @@ Example of bad backport commit message:: * Add method A to the spam module * Update the documentation of the spam module -Editing a Pull Request Prior to Merging +Editing a pull request prior to merging --------------------------------------- When a pull request submitter has enabled the `Allow edits from maintainers`_ diff --git a/getting-started/index.rst b/getting-started/index.rst index 420f1231c9..18f7d5cd55 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -1,5 +1,5 @@ =============== -Getting Started +Getting started =============== .. toctree:: diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 5c81d0a99c..9e361f25d5 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -3,7 +3,7 @@ .. _pullrequest: =========================== -Lifecycle of a Pull Request +Lifecycle of a pull request =========================== .. highlight:: bash @@ -19,7 +19,7 @@ the official CPython repository (``upstream``). .. _pullrequest-quickguide: -Quick Guide +Quick guide =========== `Clear communication`_ is key to contributing to any project, especially an @@ -70,7 +70,7 @@ Here is a quick overview of how you can contribute to CPython: .. _pullrequest-steps: -Step-by-step Guide +Step-by-step guide ================== You should have already :ref:`set up your system `, @@ -152,7 +152,7 @@ You should have already :ref:`set up your system `, .. _resolving-merge-conflicts: -Resolving Merge Conflicts +Resolving merge conflicts ------------------------- When merging changes from different branches (or variants of a branch on @@ -181,7 +181,7 @@ for a detailed technical explanation. .. _good-prs: -Making Good PRs +Making good PRs =============== When creating a pull request for submission, there are several things that you @@ -274,7 +274,7 @@ making a complete patch. .. _good-commits: -Making Good Commits +Making good commits =================== Each feature or bugfix should be addressed by a single pull request, @@ -386,7 +386,7 @@ another so they can easily verify whether their comments have been addressed. The commits will be squashed when the pull request is merged. -Converting an Existing Patch from b.p.o to GitHub +Converting an existing patch from b.p.o to GitHub ================================================= When a patch exists in the `issue tracker`_ that should be converted into a @@ -430,7 +430,7 @@ thus iterate until a satisfactory solution has emerged. .. _how-to-review-a-pull-request: -How to Review a Pull Request +How to review a pull request ---------------------------- One of the bottlenecks in the Python development @@ -471,7 +471,7 @@ code and leave comments in the pull request or issue tracker. However, please be aware that if you are recommending a pull request as 'merge-ready', you should always make sure the entire test suite passes. -Leaving a Pull Request Review on GitHub +Leaving a pull request review on GitHub ======================================= When you review a pull request, you should provide additional details and context @@ -487,7 +487,7 @@ Instead of simply "approving" the pull request, leave comments. For example: #. Comment on what is "good" about the pull request, not just the "bad". Doing so will make it easier for the PR author to find the good in your comments. -Dismissing Review from Another Core Developer +Dismissing review from another core developer ============================================= A core developer can dismiss another core developer's review if they confirmed @@ -496,7 +496,7 @@ the PR to themselves, then it is a sign that they are actively looking after the PR, and their review should not be dismissed. -Committing/Rejecting +Committing/rejecting ==================== Once your pull request has reached an acceptable state (and thus considered diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index e91ee07b8f..6e6cf8cf2b 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -2,7 +2,7 @@ .. _setup: ================== -Setup and Building +Setup and building ================== .. highlight:: console @@ -604,7 +604,7 @@ To overcome this problem, auto-generated files are also checked into the Git repository. So if you don't touch the auto-generation scripts, there's no real need to auto-generate anything. -Editors and Tools +Editors and tools ================= Python is used widely enough that practically all code editors have some form @@ -733,7 +733,7 @@ up from where you left off! .. _codespaces-use-locally: -Use Codespaces Locally +Use Codespaces locally ---------------------- On the bottom left side of the codespace screen you will see a green or grey diff --git a/index.rst b/index.rst index 82327d46a3..71583b6ca3 100644 --- a/index.rst +++ b/index.rst @@ -11,7 +11,7 @@ community that maintains Python. We welcome your contributions to Python! .. _quick-reference: -Quick Reference +Quick reference --------------- Here are the basic steps needed to get set up and contribute a patch. @@ -78,7 +78,7 @@ instructions please see the :ref:`setup guide `. Agreement (CLA) as described in the :ref:`Licensing ` section of this guide. -Quick Links +Quick links ----------- Here are some links that you probably will reference frequently while @@ -148,7 +148,7 @@ happen and that process is also described as part of this guide: * :ref:`langchanges` -Other Interpreter Implementations +Other interpreter implementations --------------------------------- This guide is specifically for contributing to the Python reference interpreter, @@ -176,7 +176,7 @@ developers to work on them. Some major examples that may be of interest are: and learning to code on low-cost microcontroller boards. -Key Resources +Key resources ------------- * Coding style guides @@ -195,7 +195,7 @@ Key Resources .. _resources: -Additional Resources +Additional resources -------------------- * Anyone can clone the sources for this guide. See @@ -217,7 +217,7 @@ Additional Resources * :ref:`Search this guide ` -Code of Conduct +Code of conduct --------------- Please note that all interactions on `Python Software Foundation `__-supported @@ -236,7 +236,7 @@ Moved to :ref:`versions` .. _contents: -Full Table of Contents +Full table of contents ---------------------- .. toctree:: diff --git a/internals/compiler.rst b/internals/compiler.rst index 7312fdcbd3..d7853456d8 100644 --- a/internals/compiler.rst +++ b/internals/compiler.rst @@ -1,7 +1,7 @@ .. _compiler: =============== -Compiler Design +Compiler design =============== .. highlight:: none @@ -40,7 +40,7 @@ Various C files, including :cpy-file:`Parser/parser.c` are generated from these (see :ref:`grammar`). -Abstract Syntax Trees (AST) +Abstract syntax trees (AST) =========================== .. _compiler-ast-trees: @@ -129,7 +129,7 @@ this case) a ``stmt_ty`` struct with the appropriate initialization. The initializes the *name*, *args*, *body*, and *attributes* fields. -Memory Management +Memory management ================= Before discussing the actual implementation of the compiler, a discussion of @@ -163,7 +163,7 @@ are very rare. However, if you've allocated a PyObject, you must tell the arena about it by calling ``PyArena_AddPyObject()``. -Source Code to AST +Source code to AST ================== The AST is generated from source code using the function @@ -290,7 +290,7 @@ number is passed as the last parameter to each ``stmt_ty`` function. .. seealso:: :pep:`617` (PEP 617 -- New PEG parser for CPython) -Control Flow Graphs +Control flow graphs =================== A *control flow graph* (often referenced by its acronym, CFG) is a @@ -336,7 +336,7 @@ output order) by doing a post-order depth-first search on the CFG following the edges. -AST to CFG to Bytecode +AST to CFG to bytecode ====================== With the AST created, the next step is to create the CFG. The first step @@ -441,7 +441,7 @@ flattening and then a ``PyCodeObject`` is created. All of this is handled by calling ``assemble()``. -Introducing New Bytecode +Introducing new bytecode ======================== Sometimes a new feature requires a new opcode. But adding new bytecode is @@ -495,7 +495,7 @@ bytecode of frozen importlib files. You have to run ``make`` again after this for recompiling generated C files. -Code Objects +Code objects ============ The result of ``PyAST_CompileObject()`` is a ``PyCodeObject`` which is defined in @@ -507,7 +507,7 @@ will also need a new case statement for the new opcode in the big switch statement in ``_PyEval_EvalFrameDefault()``. -Important Files +Important files =============== * :cpy-file:`Parser/` @@ -614,7 +614,7 @@ Important Files (named ``MAGIC_NUMBER``) for bytecode versioning. -Known Compiler-related Experiments +Known compiler-related experiments ================================== This section lists known experiments involving the compiler (including diff --git a/internals/exploring.rst b/internals/exploring.rst index b049159af8..3a812d1a91 100644 --- a/internals/exploring.rst +++ b/internals/exploring.rst @@ -1,7 +1,7 @@ .. _exploring: ======================== -Exploring the Internals +Exploring the internals ======================== This is a quick guide for people who are interested in learning more about @@ -9,7 +9,7 @@ CPython's internals. It provides a summary of the source code structure and contains references to resources providing a more in-depth view. -CPython Source Code Layout +CPython source code layout ========================== This guide gives an overview of CPython's code structure. @@ -49,7 +49,7 @@ Some exceptions: * Windows-only module ``winreg`` is at :cpy-file:`PC/winreg.c` -Additional References +Additional references ===================== For over 20 years the CPython code base has been changing and evolving. diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst index ab6b35c7a0..c2cbf6d72e 100644 --- a/internals/garbage-collector.rst +++ b/internals/garbage-collector.rst @@ -3,7 +3,7 @@ .. _garbage_collector: ======================== -Garbage Collector Design +Garbage collector design ======================== :Author: Pablo Galindo Salgado diff --git a/internals/index.rst b/internals/index.rst index 1611135609..4e9d28c83a 100644 --- a/internals/index.rst +++ b/internals/index.rst @@ -1,5 +1,5 @@ =================== -CPython's Internals +CPython's internals =================== .. toctree:: diff --git a/internals/interpreter.rst b/internals/interpreter.rst index 68d5017d24..003d5de13d 100644 --- a/internals/interpreter.rst +++ b/internals/interpreter.rst @@ -1,7 +1,7 @@ .. _interpreter: =============================== -The Bytecode Interpreter (3.11) +The bytecode interpreter (3.11) =============================== .. highlight:: c diff --git a/internals/parser.rst b/internals/parser.rst index aa035c1a77..18fd752032 100644 --- a/internals/parser.rst +++ b/internals/parser.rst @@ -1,7 +1,7 @@ .. _parser: =================== -Guide to the Parser +Guide to the parser =================== :Author: Pablo Galindo Salgado @@ -24,7 +24,7 @@ outputs the parser. The way the Python language is changed is therefore by modifying the grammar file and developers rarely need to interact with the parser generator itself other than use it to generate the parser. -How PEG Parsers Work +How PEG parsers work ==================== .. _how-peg-parsers-work: @@ -159,7 +159,7 @@ the rule: :: If the return type is omitted, then a ``void *`` is returned in C and an ``Any`` in Python. -Grammar Expressions +Grammar expressions ------------------- ``# comment`` @@ -306,7 +306,7 @@ and "hidden left-recursion" like:: rule: 'optional'? rule '@' some_other_rule -Variables in the Grammar +Variables in the grammar ------------------------ A sub-expression can be named by preceding it with an identifier and an @@ -641,7 +641,7 @@ when writing actions. In the C parser, some of these automatic variable names ar which is normally used to create AST nodes as almost all constructors need these attributes to be provided. All of the location variables are taken from the location information of the current token. -Hard and Soft keywords +Hard and soft keywords ---------------------- .. note:: @@ -722,7 +722,7 @@ error messages. tokenizer errors such as unclosed parenthesis will be reported only after the parser finishes without returning anything. -How Syntax errors are reported +How syntax errors are reported ------------------------------ As described previously in the :ref:`how PEG parsers work section diff --git a/testing/buildbots.rst b/testing/buildbots.rst index e9ccbcab0b..38e6063647 100644 --- a/testing/buildbots.rst +++ b/testing/buildbots.rst @@ -1,7 +1,7 @@ .. _buildbots: ====================== -Working with Buildbots +Working with buildbots ====================== .. highlight:: bash @@ -36,7 +36,7 @@ need assistance with the buildbots, a good way to get help is to either: worker owners are subscribed; or * contact the release manager of the branch you have issues with. -Buildbot failures on Pull Requests +Buildbot failures on pull requests ================================== The ``bedevere-bot`` on GitHub will put a message on your merged Pull Request diff --git a/testing/coverage.rst b/testing/coverage.rst index 49a2ff1298..a28fb06dba 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -1,7 +1,7 @@ .. _coverage: ====================== -Increase Test Coverage +Increase test coverage ====================== Python development follows a practice that all semantic changes and additions @@ -36,7 +36,7 @@ explicit coverage of the module is from its own set of tests instead of from implicit testing by other code that happens to use the module. -Common Gotchas +Common gotchas ============== Please realize that coverage reports on modules already imported before coverage @@ -54,7 +54,7 @@ prefer that other types of tests not be used (e.g., blackbox). When in doubt, stick with whitebox testing in order to properly exercise the code. -Measuring Coverage +Measuring coverage ================== It should be noted that a quirk of running coverage over Python's own stdlib is @@ -79,7 +79,7 @@ provided by the stdlib then you can :ref:`use test.regrtest .. _install_coverage: -Install Coverage +Install coverage '''''''''''''''' By default, pip will not install into the in-development version of Python you @@ -122,7 +122,7 @@ it. For this, you will again need to use the full path to that installation. .. _coverage_usage: -Basic Usage +Basic usage ''''''''''' The following command will tell you if your copy of coverage works (substitute @@ -176,7 +176,7 @@ with pages that visibly show what lines of code were or were not executed. .. _branch_coverage: -Branch Coverage +Branch coverage ''''''''''''''' For the truly daring, you can use another powerful feature of coverage.py: @@ -193,7 +193,7 @@ This will lead to the report stating not only what lines were not covered, but also what branch paths were not executed. -Coverage Results For Modules Imported Early On +Coverage results for modules imported early on '''''''''''''''''''''''''''''''''''''''''''''' For the *truly truly* daring, you can use a hack to get coverage.py to include @@ -256,7 +256,7 @@ files for each executed module along with which lines were executed how many times. -Filing the Issue +Filing the issue ================ Once you have increased coverage, you need to create an issue on the `issue tracker`_ and diff --git a/testing/index.rst b/testing/index.rst index 4a7247c985..770c258000 100644 --- a/testing/index.rst +++ b/testing/index.rst @@ -1,5 +1,5 @@ ===================== -Testing and Buildbots +Testing and buildbots ===================== .. toctree:: diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 1beaa3afa9..6f2dacace8 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -2,7 +2,7 @@ .. _buildworker: ==================== -New Buildbot Workers +New buildbot workers ==================== .. highlight:: bash @@ -274,7 +274,7 @@ or, if possible, providing ssh access to a committer to run experiments to try to resolve the issue. -Required Ports +Required ports ============== The worker operates as a *client* to the *buildmaster*. This means that @@ -304,7 +304,7 @@ Many tests will also create local TCP sockets and connect to them, usually using either ``localhost`` or ``127.0.0.1``. -Required Resources +Required resources ================== Based on the last time we did a `survey @@ -322,7 +322,7 @@ that Python compiles correctly on the platform and can run the rest of the test suite. -Security Considerations +Security considerations ======================= We only allow builds to be triggered against commits to the diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index f9323463a9..14ef0c6869 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -2,7 +2,7 @@ .. _runtests: ========================= -Running and Writing Tests +Running and writing tests ========================= .. note:: @@ -97,7 +97,7 @@ you want the most thorough tests you should use the strenuous approach shown above. -Unexpected Skips +Unexpected skips ---------------- Sometimes when running the test suite, you will see "unexpected skips" diff --git a/testing/silence-warnings.rst b/testing/silence-warnings.rst index e32da9a9c3..e46a11a022 100644 --- a/testing/silence-warnings.rst +++ b/testing/silence-warnings.rst @@ -2,7 +2,7 @@ .. _silencewarnings: ==================================== -Silence Warnings From the Test Suite +Silence warnings from the test suite ==================================== When running Python's test suite, no warnings should result when you run it diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index 1027056ff7..1385be052a 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -2,7 +2,7 @@ .. _gh-faq: =========================== -GitHub Issues for BPO Users +GitHub issues for BPO users =========================== Here are some frequently asked questions about how to do things in @@ -82,7 +82,7 @@ automatically mark a task as complete if the other referenced issue is closed. More details in the `official GitHub documentation `_. -What on Earth is a "mannequin"? +What on earth is a "mannequin"? =============================== For issues migrated to GitHub from `bpo`_ where the authors or commenters @@ -97,12 +97,12 @@ that happened in the issue. In case the user did share their GitHub account name in their `bpo`_ profile, we use that. Otherwise, their classic `bpo`_ username is used instead. -Where did the "Resolution" field go? +Where did the "resolution" field go? ==================================== Based on historical data we found it not being used very often. -Where did the "Low", "High", and "Critical" priorities go? +Where did the "low", "high", and "critical" priorities go? ========================================================== Based on historical data we found those not being used very often. diff --git a/triage/index.rst b/triage/index.rst index b2ae1c5737..a054ad62f2 100644 --- a/triage/index.rst +++ b/triage/index.rst @@ -1,5 +1,5 @@ =================== -Issues and Triaging +Issues and triaging =================== .. toctree:: diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 889d71e9ab..0f93df9caf 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -2,11 +2,11 @@ .. _tracker: ============= -Issue Tracker +Issue tracker ============= -Using the Issue Tracker +Using the issue tracker ======================= If you think you have found a bug in Python, you can report it to the @@ -124,7 +124,7 @@ By writing :samp:`Duplicate of #{NNN}` in a comment, you can `mark issues and PRs as duplicates `_. -Disagreement With a Resolution on the Issue Tracker +Disagreement with a resolution on the issue tracker =================================================== As humans, we will have differences of opinions from time to time. First and diff --git a/triage/labels.rst b/triage/labels.rst index 95e84558b6..7cee20af88 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -2,7 +2,7 @@ .. _gh-labels: ============= -GitHub Labels +GitHub labels ============= Triagers, core developers and bots can add labels on GitHub diff --git a/triage/triaging.rst b/triage/triaging.rst index 9e0a621553..6ad96eeff5 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -1,14 +1,14 @@ .. _triaging: ================= -Triaging an Issue +Triaging an issue ================= This section of the devguide documents the :ref:`issue tracker ` for users and developers. -Checklist for Triaging +Checklist for triaging ====================== * Read the initial message and the comments. @@ -44,7 +44,7 @@ a team member, likely a triager or a core developer. .. _helptriage: -Helping Triage Issues +Helping triage issues ===================== Once you know your way around how Python's source files are @@ -56,7 +56,7 @@ Around the clock, new issues are being opened on the :ref:`issue tracker ` and existing issues are being updated. Every issue needs to be triaged to make sure everything runs smoothly. -Classifying Reports +Classifying reports ------------------- For bugs, an issue needs to: @@ -81,7 +81,7 @@ This is all helpful as it allows members of the :ref:`triage team ` to properly classify an issue so it can be handled by the right core developers in a timely fashion. -Reviewing Pull Requests +Reviewing pull requests ----------------------- If an issue has a linked pull request that has not been reviewed, @@ -101,7 +101,7 @@ experience working on Python's code base will notice. See also :ref:`committing`. -Finding an Issue You Can Help With +Finding an issue you can help with ---------------------------------- If you want to help with triaging, you might also want to search for issues diff --git a/versions.rst b/versions.rst index 78224b09d8..b712dfc6e3 100644 --- a/versions.rst +++ b/versions.rst @@ -2,7 +2,7 @@ .. _branchstatus: ========================= -Status of Python Versions +Status of Python versions ========================= The ``main`` branch is currently the future Python 3.13, and is the only @@ -10,13 +10,13 @@ branch that accepts new features. The latest release for each Python version can be found on the `download page `_. -Python Release Cycle +Python release cycle ==================== .. raw:: html :file: include/release-cycle.svg -Supported Versions +Supported versions ================== Dates shown in *italic* are scheduled and can be adjusted. @@ -29,7 +29,7 @@ Dates shown in *italic* are scheduled and can be adjusted. .. Remember to update main branch in the paragraph above too -Unsupported Versions +Unsupported versions ==================== .. csv-table:: @@ -38,7 +38,7 @@ Unsupported Versions :file: include/end-of-life.csv -Status Key +Status key ========== :feature: new features, bugfixes, and security fixes are accepted.