- Getting started
- Development workflow
- Issues and triaging
- Documentation
- Testing and buildbots
- Development tools
- Core team
- CPython’s internals
- Status of Python versions
- Python Contributor’s Guide (draft)
- [Plan for the Contributor’s Guide]
- Introduction
- The CPython project
- Issues and triaging
- Documentation contributions
- Code contributions
- Core team
- Accessibility, design, and user success
- Security and infrastructure contributions
- Workflows
Important
This is part of aDraft of the Python Contributor’s Guide.Text in square brackets are notes about content to fill in.Currently, the devguide and this new Contributor’s Guide co-exist in therepo. We are using Sphinx include directives to demonstrate the re-organization.The final Contributor’s Guide will replace the devguide with content in only oneplace.We welcome help with this!
The[Plan for the Contributor’s Guide] page has more details about the current state of this draftandhow you can help. See more info about the Contributor Guide in thediscussion forum:Refactoring the DevGuide.
Regenerating auto-created files¶
Note
[These are two similar sections from the is theSetup and building section from the devguide.]
Regenerateconfigure¶
If a change is made to Python which relies on some POSIX system-specificfunctionality (such as using a new system call), it is necessary to update theconfigure script to test for availability of the functionality.Python’sconfigure script is generated fromconfigure.acusingGNU Autoconf.
After editingconfigure.ac, runmakeregen-configure to generateconfigure,pyconfig.h.in, andaclocal.m4.When submitting a pull request with changes made toconfigure.ac,make sure you also commit the changes in the generated files.
Python’sconfigure.ac script requires a specific version ofGNU Autoconf.For Python 3.12 and newer, GNU Autoconf v2.71 is required.For Python 3.11 and earlier, GNU Autoconf v2.69 is required.
The recommended and by far the easiest way to regenerateconfigure is:
$ make regen-configure
This will use Podman or Docker to do the regeneration with the proper versionof GNU Autoconf.
If you cannot (or don’t want to) usemakeregen-configure,install theautoconf-archive andpkg-config utilities,and make sure thepkg.m4 macro file located in the appropriateaclocal location:
$ ls $(aclocal --print-ac-dir) | grep pkg.m4
Note
Runningautoreconf is not the same as runningautoconf.For example, runningautoconf by itself will not regeneratepyconfig.h.in.autoreconf runsautoconf and a number of other toolsrepeatedly as appropriate.
Regenerate the ABI dump¶
Maintenance branches (notmain) have a special file located inDoc/data/pythonX.Y.abi that allows us to know if a given pull requestaffects the public ABI. This file is used by the GitHub CI in a checkcalledCheckiftheABIhaschanged that will fail if a given pull requesthas changes to the ABI and the ABI file is not updated.
This check acts as a fail-safe anddoesn’t necessarily mean that the pullrequest cannot be merged. When this check fails you should add the relevantrelease manager to the PR so that they are aware of the change and they canvalidate if the change can be made or not.
Important
ABI changes are allowed before the first release candidate. After the first releasecandidate, all further releases must have the same ABI for ensuring compatibilitywith native extensions and other tools that interact with the Python interpreter.See the documentation about therelease candidate phase.
When the PR check fails, the associated run will have the updated ABI fileattached as an artifact. After release manager approval, you can download andadd this file into your PR to pass the check.
You can regenerate the ABI file by yourself by invoking theregenabidumpMake target. Note that for doing this you need to regenerate the ABI file inthe same environment that the GitHub CI uses to check for it. This is becausedifferent platforms may include some platform-specific details that make thecheck fail even if the Python ABI is the same. The easier way to regeneratethe ABI file using the same platform as the CI uses is by using Docker:
# In the CPython root:$ docker run -v$(pwd):/src:Z -w /src --rm -it ubuntu:22.04 \ bash /src/.github/workflows/regen-abidump.sh
Note that theubuntu version used to execute the script matters andmust match the version used by the CI to check the ABI. See the.github/workflows/build.yml file for more information.