├── static └── .hidden ├── .gitignore ├── requirements.txt ├── python_dev.rst ├── community.rst ├── update_bpo_pr.rst ├── python_fix.rst ├── ideas.rst ├── c_fix.rst ├── getting_started.rst ├── Makefile ├── diversity.rst ├── review.rst ├── code_of_conduct.rst ├── open_bpo.rst ├── communication_channels.rst ├── make.bat ├── index.rst ├── README.md ├── continuous_integration.rst ├── internals.rst ├── pr.rst ├── run_tests.rst ├── getting_help.rst ├── where_should_i_start.rst ├── conf.py └── core_developer.rst /static/.hidden: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build 2 | 3 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx 2 | -------------------------------------------------------------------------------- /python_dev.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++++++++++ 2 | python-dev mailing list 3 | +++++++++++++++++++++++ 4 | 5 | To discuss more in depth the actual implementation of a feature, the python-dev 6 | mailing list is the appropriate place. 7 | 8 | * https://mail.python.org/mailman/listinfo/python-dev 9 | * https://mail.python.org/pipermail/python-dev/ 10 | -------------------------------------------------------------------------------- /community.rst: -------------------------------------------------------------------------------- 1 | Python Community 2 | ================ 3 | 4 | Goals: 5 | 6 | * Know the CPython community, code of conduct, the diversity statement and 7 | communication channels 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | :caption: Contents: 12 | 13 | code_of_conduct.rst 14 | diversity.rst 15 | communication_channels.rst 16 | 17 | Badge: "community". 18 | -------------------------------------------------------------------------------- /update_bpo_pr.rst: -------------------------------------------------------------------------------- 1 | ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 | Lifetime of a change: bugs.python.org and PR updates 3 | ++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 | 5 | First, nothing happens 6 | ====================== 7 | 8 | XXX 9 | 10 | First feedback 11 | ============== 12 | 13 | XXX 14 | 15 | Update your PR 16 | ============== 17 | 18 | XXX 19 | -------------------------------------------------------------------------------- /python_fix.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++++++++++++++ 2 | Write your first Python fix 3 | +++++++++++++++++++++++++++ 4 | 5 | Goal: be able to write a Python fix with an unit test, but not publish it. 6 | 7 | How to find a bug or feature to write 8 | ===================================== 9 | 10 | XXX 11 | 12 | Write the code 13 | ============== 14 | 15 | XXX 16 | 17 | Add an unit test 18 | ================ 19 | 20 | XXX 21 | 22 | Check for non-regression 23 | ======================== 24 | 25 | XXX 26 | 27 | -------------------------------------------------------------------------------- /ideas.rst: -------------------------------------------------------------------------------- 1 | ++++++++++++++++ 2 | Propose new idea 3 | ++++++++++++++++ 4 | 5 | To propose new ideas, the python-ideas mailing list is the appropriate place. 6 | 7 | * `The python-idea mailing list 8 | `_ 9 | * `python-ideas archives `_ 10 | * `LWN: Things that won't change in Python 11 | `_ 12 | * `LWN: Ideas versus implementation 13 | `_ 14 | -------------------------------------------------------------------------------- /c_fix.rst: -------------------------------------------------------------------------------- 1 | ++++++++++++++++++++++ 2 | Write your first C fix 3 | ++++++++++++++++++++++ 4 | 5 | Goal: be able to write a C fix with an unit test (but not publish it). 6 | 7 | How to find a bug or feature to write 8 | ===================================== 9 | 10 | XXX 11 | 12 | Write the code 13 | ============== 14 | 15 | XXX 16 | 17 | Add an unit test 18 | ================ 19 | 20 | XXX 21 | 22 | Check for non-regression 23 | ======================== 24 | 25 | XXX 26 | 27 | Check for reference leaks 28 | ========================= 29 | 30 | Run your test using:: ``./python -m test -R 3:3 test_xxx``. 31 | 32 | -------------------------------------------------------------------------------- /getting_started.rst: -------------------------------------------------------------------------------- 1 | Getting Started 2 | =============== 3 | 4 | Goals: 5 | 6 | * Get a running Python executable built manually 7 | * Run basic sanity checks to make sure that your executable is working 8 | 9 | Requirements: 10 | 11 | * Know CPython, Git and the C compiler of your operating system 12 | 13 | .. toctree:: 14 | :maxdepth: 1 15 | :caption: Contents: 16 | 17 | build_cpython_linux.rst 18 | build_cpython_windows.rst 19 | build_cpython_macos.rst 20 | 21 | For more information about the compilation, you can read the compiling section 22 | of the `devguide 23 | `_. 24 | 25 | Badge: "getting_started". 26 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SPHINXPROJ = TutorialtocontributetotheCPythonproject 8 | SOURCEDIR = . 9 | BUILDDIR = build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /diversity.rst: -------------------------------------------------------------------------------- 1 | +++++++++ 2 | Diversity 3 | +++++++++ 4 | 5 | Diversity Statement: 6 | 7 | The Python Software Foundation and the global Python community welcome and 8 | encourage participation by everyone. Our community is based on mutual 9 | respect, tolerance, and encouragement, and we are working to help each 10 | other live up to these principles. We want our community to be more 11 | diverse: whoever you are, and whatever your background, we welcome you. 12 | 13 | * https://www.python.org/community/diversity/ 14 | * http://wiki.python.org/moin/DiversityInPython 15 | 16 | For example, don't say "hey *guys*!" but "hey **everyone**!". 17 | 18 | Action: [ Click to confirm that you read the diversity statement :-) ] 19 | -------------------------------------------------------------------------------- /review.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++++++++++++++++ 2 | Review bugs and pull requests 3 | +++++++++++++++++++++++++++++ 4 | 5 | Reading code written by others can be a good practice to learn from others, and 6 | learn the Python workflow. 7 | 8 | The repository on GitHub has a page for the `Pull Requests `_ (PR) and in this case, you could go on the page and review the proposed PR. 9 | 10 | For example, we prefer to review the `PR where the CLA is signed `_ 11 | 12 | Usually, if the CLA is not signed by the contributor, we prefer to ask to sign the document and wait for 3 business days, its bugs.python.org account will then be updated. 13 | -------------------------------------------------------------------------------- /code_of_conduct.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++ 2 | Code Of Conduct 3 | +++++++++++++++ 4 | 5 | The Python community wants to be welcome and fair with everyone and so has 6 | written down a code of conduct to decide how to handle conflicts: `Python 7 | Community Code of Conduct `_. 8 | 9 | The Code of Conduct applies to most, if not all, Python mailing lists, to the 10 | bug tracker, etc. 11 | 12 | Questions/comments/reports? See the contact information at the end of `Python 13 | Community Code of Conduct `_. 14 | 15 | See also `Proposal for procedures regarding CoC actions 16 | `_. 17 | 18 | Action: [ Click to confirm that you read the code of conduct :-) ] 19 | -------------------------------------------------------------------------------- /open_bpo.rst: -------------------------------------------------------------------------------- 1 | ++++++++++++++++++++++++++++++++++++++++ 2 | Open your first issue on bugs.python.org 3 | ++++++++++++++++++++++++++++++++++++++++ 4 | 5 | Required badge: "community". 6 | 7 | Create your account 8 | =================== 9 | 10 | * http://bugs.python.org/ 11 | * Click on [Register] 12 | * Fill the form 13 | * XXX 14 | * Confirm your email 15 | * XXX 16 | 17 | Open your issue 18 | =============== 19 | 20 | * Log in 21 | * Click on [Create New] 22 | * Write a short title 23 | * Describe the bug or feature request 24 | * [Submit New Entry] 25 | 26 | Bug fix 27 | ======== 28 | 29 | Complete your issue for a bug fix: 30 | 31 | * Specify the OS 32 | * Specify your Python version 33 | * Write a script to reproduce the bug, the best is if the script doesn't use 34 | third-party modules 35 | 36 | Feature request 37 | =============== 38 | 39 | XXX 40 | 41 | Congrats! Next section: XXX 42 | 43 | Badge: "first bpo created". 44 | -------------------------------------------------------------------------------- /communication_channels.rst: -------------------------------------------------------------------------------- 1 | ++++++++++++++++++++++++++++++ 2 | CPython Communication Channels 3 | ++++++++++++++++++++++++++++++ 4 | 5 | Communication Channels 6 | ====================== 7 | 8 | * IRC: #python-dev on Freenode 9 | * Main Mailing lists: 10 | 11 | * python-ideas 12 | * python-dev 13 | 14 | Physical meetings 15 | ================= 16 | 17 | * Pycon US: https://us.pycon.org/ 18 | * Language Summit, during Pycon US 19 | 20 | * 2017: https://us.pycon.org/2017/events/language-summit/ 21 | * LWN report, 2017: https://lwn.net/Articles/723251/ 22 | * LWN report, 2016: https://lwn.net/Articles/688969/ 23 | * LWN report, 2015: https://lwn.net/Articles/639773/ 24 | * XXX: [recent group photo] 25 | 26 | * EuroPython: no formal meeting, discussions in the corridor usually 27 | * CPython sprints: 28 | 29 | * 2016: http://blog.python.org/2016/09/python-core-development-sprint-2016-36.html 30 | 31 | Action: [ Click to confirm that you read everything :-) ] 32 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=build 12 | set SPHINXPROJ=TutorialtocontributetotheCPythonproject 13 | 14 | if "%1" == "" goto help 15 | 16 | %SPHINXBUILD% >NUL 2>NUL 17 | if errorlevel 9009 ( 18 | echo. 19 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 20 | echo.installed, then set the SPHINXBUILD environment variable to point 21 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 22 | echo.may add the Sphinx directory to PATH. 23 | echo. 24 | echo.If you don't have Sphinx installed, grab it from 25 | echo.http://sphinx-doc.org/ 26 | exit /b 1 27 | ) 28 | 29 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 30 | goto end 31 | 32 | :help 33 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 34 | 35 | :end 36 | popd 37 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. Tutorial to contribute to the CPython project documentation master file, created by 2 | sphinx-quickstart on Sun Jul 16 16:31:07 2017. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | Welcome to Tutorial to contribute to the CPython project's documentation! 7 | ========================================================================= 8 | 9 | .. toctree:: 10 | :maxdepth: 2 11 | :caption: Contents: 12 | 13 | getting_help.rst 14 | getting_started.rst 15 | where_should_i_start.rst 16 | community.rst 17 | run_tests.rst 18 | python_fix.rst 19 | c_fix.rst 20 | open_bpo.rst 21 | pr.rst 22 | update_bpo_pr.rst 23 | review.rst 24 | ideas.rst 25 | python_dev.rst 26 | continuous_integration.rst 27 | core_developer.rst 28 | internals.rst 29 | 30 | Contribute to these documents `at Github `_. 31 | 32 | Indices and tables 33 | ================== 34 | 35 | * :ref:`genindex` 36 | * :ref:`modindex` 37 | * :ref:`search` 38 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | This old documentation is **no longer maintained**. Read the 2 | [Python Developer’s Guide](https://devguide.python.org/) instead. 3 | 4 | # Description 5 | 6 | Tutorial to contribute to the CPython project. 7 | 8 | # Design and goal of the tutorial 9 | 10 | The final goal is to train contributors to promote them to CPython core 11 | developers. That's the long term goal. 12 | 13 | The short term goal is to fill the gap in the current devguide between 14 | "compile/install python" and "congrats! you are now a CPython core developer!". 15 | Document all the things expected to be known to become a core developer. 16 | 17 | # Installation 18 | 19 | You need to use a installed version of [Sphinx](http://www.sphinx-doc.org/en/stable/). 20 | 21 | For that, you have two options. Firstly, use the sphinx package from your favorite distribution 22 | 23 | ## Fedora 24 | 25 | ```bash 26 | dnf install python-sphinx 27 | ``` 28 | 29 | ## Debian/Ubuntu 30 | 31 | ```bash 32 | apt-get install python3-sphinx 33 | ``` 34 | 35 | 36 | # Compilation 37 | 38 | Once you have an installed version of [Sphinx](http://www.sphinx-doc.org/en/stable/), you can build the documentation. 39 | 40 | ```bash 41 | make html 42 | ``` 43 | 44 | The result will be in `build/html/index.html` 45 | 46 | You can check it via [http://localhost:8000](http://localhost:8000) if you run the following commands 47 | 48 | ```bash 49 | cd build/html/ 50 | python3 -m http.server 51 | ``` 52 | -------------------------------------------------------------------------------- /continuous_integration.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++++++++++++++ 2 | Continuous Integration (CI) 3 | +++++++++++++++++++++++++++ 4 | 5 | Travis CI 6 | ========= 7 | 8 | XXX 9 | 10 | Configuration: ``.travis.yml`` file. 11 | 12 | 13 | AppVeyor 14 | ======== 15 | 16 | XXX 17 | 18 | Configuration: ``.github/appveyor.yml`` file. 19 | 20 | 21 | Buildbots 22 | ========= 23 | 24 | * `python-buildbots mailing list 25 | `_ 26 | * `buildbot-status mailing list 27 | `_ 28 | 29 | CPython is running a `Buildbot `_ server for continuous 30 | integration, but tests are run as post-commit: see `Python buildbots 31 | `_. 32 | 33 | Buildbot "waterfall" views: 34 | 35 | * `Python master ("3.x") `_ 36 | * `Python 3.6 `_ 37 | * `Python 3.5 `_ 38 | * `Python 2.7 `_ 39 | 40 | The buildbot configuration can be found in the `buildmaster-config project 41 | `_ (start with the 42 | ``master/master.cfg`` file). 43 | 44 | -------------------------------------------------------------------------------- /internals.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++++++++++++++++++++++ 2 | Documentations of CPython internals 3 | +++++++++++++++++++++++++++++++++++ 4 | 5 | * The official `Python Developer’s Guide 6 | `_ 7 | * `Your Guide to the CPython Source Code 8 | `_ 9 | (Aug 2019) by Anthony Shaw 10 | * Prashanth Raghu's documentation: 11 | 12 | * `Internals of CPython 2.7 13 | `_ 14 | * `Internals of CPython 3.6 15 | `_ 16 | * `Advanced Internals of CPython 3.6 17 | `_ 18 | 19 | * `Python Development Documentation 20 | `_ by Victor Stinner 21 | * `CPython internals: A ten-hour codewalk through the Python interpreter source 22 | code `_ 23 | (October 2014) by Philip Guo 24 | * `Lifecycle of a Python Code - CPython's Execution Model 25 | `_ 26 | by Batuhan Osman Taşkaya (October 2018) 27 | * `A Python Interpreter Written in Python 28 | `_ 29 | (2016) by Allison Kaptur, from `500 Lines or Less 30 | `_ book. 31 | -------------------------------------------------------------------------------- /pr.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++++++++++++++++ 2 | Write your first Pull Request 3 | +++++++++++++++++++++++++++++ 4 | 5 | Required badge: "community". 6 | 7 | Create your GitHub account 8 | ========================== 9 | 10 | If you already have a GitHub account, skip this section ;-) 11 | 12 | * https://github.com/ 13 | * Click on [Sign up] 14 | * Fill the form 15 | * XXX 16 | * Confirm your email 17 | * XXX 18 | 19 | 20 | Link your bugs.python.org account to your GitHub account 21 | ======================================================== 22 | 23 | * Go to your bugs.python.org account 24 | * Go to "Your Details" 25 | * Set the **GitHub name** field 26 | * Submit your changes 27 | 28 | 29 | Sign the CLA 30 | ============ 31 | 32 | Sign the Python Contributor Agreement. 33 | 34 | * Sign https://www.python.org/psf/contrib/contrib-form/ 35 | * Wait... the confirmation is done manually by humans, so be prepared to wait 36 | up to one week (usually 3 business days) 37 | 38 | For legal question, you can send an email to `legal@python.org `_ . 39 | 40 | 41 | Create a local Git branch 42 | ========================= 43 | 44 | Once you have your patch (see XXX Python or XXX C fix sections), make sure that 45 | your changes are in a local branch:: 46 | 47 | git checkout -b mybranch 48 | 49 | Template of a commit message:: 50 | 51 | bpo-12345: fix a bug in the email module 52 | 53 | Fix a race condition in the email module. Before xxx failed. It now works 54 | well! 55 | 56 | 57 | Git remotes 58 | =========== 59 | 60 | * origin: your repository 61 | * upstream: cpython/python 62 | 63 | 64 | Publish your pull request 65 | ========================= 66 | 67 | Manually 68 | -------- 69 | 70 | * git push origin HEAD 71 | * Open https://github.com/python/cpython and click on "New pull request" 72 | * Select the base fork: ``python/cpython`` and base branch: ``main`` 73 | * Select the head fork: ``/cpython`` and base branch: the branch 74 | * Press ``Create Pull Request`` button 75 | 76 | For more information: please, you could read `this section `_ of the devguide 77 | 78 | Given badge: "first pr". 79 | -------------------------------------------------------------------------------- /run_tests.rst: -------------------------------------------------------------------------------- 1 | +++++++++ 2 | Run tests 3 | +++++++++ 4 | 5 | Introduce a Bug 6 | =============== 7 | 8 | Instead of trying to write new code, let's start by writing a bug! 9 | 10 | Diff:: 11 | 12 | diff --git a/Lib/http/server.py b/Lib/http/server.py 13 | index b1151a2..f132be4 100644 14 | --- a/Lib/http/server.py 15 | +++ b/Lib/http/server.py 16 | @@ -965,6 +965,7 @@ class CGIHTTPRequestHandler(SimpleHTTPRequestHandler): 17 | rbufsize = 0 18 | 19 | def do_POST(self): 20 | + bug 21 | """Serve a POST request. 22 | 23 | This is only implemented for CGI scripts. 24 | 25 | 26 | Run tests 27 | ========= 28 | 29 | Type:: 30 | 31 | $ ./python.exe -m test -v test_httpservers 32 | 33 | We expect that tests fail:: 34 | 35 | (...) 36 | ====================================================================== 37 | ERROR: test_post (test.test_httpservers.CGIHTTPServerTestCase) 38 | ---------------------------------------------------------------------- 39 | Traceback (most recent call last): 40 | File ".../Lib/test/test_httpservers.py", line 726, in test_post 41 | res = self.request('/cgi-bin/file2.py', 'POST', params, headers) 42 | File ".../Lib/test/test_httpservers.py", line 79, in request 43 | return self.connection.getresponse() 44 | File ".../Lib/http/client.py", line 1322, in getresponse 45 | response.begin() 46 | File ".../Lib/http/client.py", line 296, in begin 47 | version, status, reason = self._read_status() 48 | File ".../Lib/http/client.py", line 265, in _read_status 49 | raise RemoteDisconnected("Remote end closed connection without" 50 | http.client.RemoteDisconnected: Remote end closed connection without response 51 | 52 | ---------------------------------------------------------------------- 53 | (...) 54 | FAILED (errors=1) 55 | (...) 56 | 57 | Re-run only the failing method:: 58 | 59 | $ ./python -m test -v -m test_post test_httpservers 60 | 61 | Find the code of the failing tests, see most recent call in the traceback:: 62 | 63 | File ".../Lib/test/test_httpservers.py", line 726, in test_post 64 | res = self.request('/cgi-bin/file2.py', 'POST', params, headers) 65 | 66 | Open Lib/test/test_httpservers.py and go to the respective line (line 726 in this case):: 67 | 68 | def test_post(self): 69 | params = urllib.parse.urlencode( 70 | {'spam' : 1, 'eggs' : 'python', 'bacon' : 123456}) 71 | headers = {'Content-type' : 'application/x-www-form-urlencoded'} 72 | res = self.request('/cgi-bin/file2.py', 'POST', params, headers) 73 | 74 | self.assertEqual(res.read(), b'1, python, 123456' + self.linesep) 75 | 76 | 77 | Fix the bug 78 | =========== 79 | 80 | * Modify Lib/http/server.py to remove ``bug``. 81 | * Re-run test_post() test 82 | 83 | Run the whole test suite 84 | ======================== 85 | 86 | * Re-run all test_httpservers tests 87 | * Run the whole test suite 88 | 89 | Run the whole test suite:: 90 | 91 | ./python.exe -m test -j0 -rW 92 | 93 | Flags: 94 | 95 | * -j0: run tests in parallel using as many test processes as your CPU permits 96 | * -r: randomize tests 97 | * -W: hide tests output on success, but show on failure 98 | -------------------------------------------------------------------------------- /getting_help.rst: -------------------------------------------------------------------------------- 1 | .. _help: 2 | 3 | Getting Help 4 | ============ 5 | 6 | This tutorial is an early draft. It is likely that you will quickly be blocked 7 | by an incomplete section (like "XXX") or a missing section. Don't hesitate to 8 | complain, ask for help, and report issues! 9 | 10 | Active Core Developers 11 | ---------------------- 12 | 13 | While the CPython team has more than 100 core developers, some of them 14 | "left" the project and are no more active. 15 | 16 | `GitHub statistics on contributors 17 | `_ can help to identify 18 | active contributors *if* you select a recent time window, like last 6 or 12 19 | months. 20 | 21 | Developers available to mentor new contributors: 22 | 23 | * Victor Stinner, lives in France, works for Red Hat, core dev since 2010. 24 | IRC nickname: ``vstinner`` on Libera.Chat. 25 | Timezone: `France (Paris) local clock `_. 26 | 27 | * Zachary (Zach) Ware, living in the US (midwest), working as an independent 28 | consultant, core dev since 2013. 29 | IRC nickname: ``zware`` on Libera.Chat. 30 | Timezone: `US/Central `_. 31 | 32 | #python-dev channel 33 | ------------------- 34 | 35 | The IRC ``#python-dev`` channel of the `Libera.Chat server 36 | `_. 37 | 38 | Some nicknames: 39 | 40 | * ``vstinner``: Victor Stinner (previously known as ``haypo``) 41 | 42 | * ``zware``: Zach Ware 43 | 44 | * ``matrixise``: Stéphane Wirtel 45 | 46 | Core-mentorship mailing list 47 | ---------------------------- 48 | 49 | * `Python Core Mentorship `_ 50 | * `The core-mentorship mailing list 51 | `_ 52 | 53 | Developer Guide 54 | --------------- 55 | 56 | * `Python Developer’s Guide `_ 57 | 58 | Contributors 59 | ------------ 60 | 61 | Contributors are also encouraged to help other contributors since new comers 62 | are the most experienced in issues to start contributing for CPython :-) 63 | 64 | * Stéphane Wirtel, living in Belgium, working as an independent consultant, contributor since 2014. 65 | IRC nickname: ``matrixise`` on Libera.Chat. 66 | Timezone: `Europe/Brussels `_. 67 | 68 | Looking for help on a specific Python module 69 | -------------------------------------------- 70 | 71 | The `Expert Index `_ lists 72 | maintainers for the some but not all Python modules. 73 | 74 | Articles and talks about Python development 75 | ------------------------------------------- 76 | 77 | * `So, You want to Contribute to Cpython : Gather here !! 78 | `_ 79 | by Joannah Nanjekye, June 2019 80 | * Talk: `Inside the Kitchen `_ 81 | by Daniel Moisset, PyLondinium 2019 82 | * `My Path to Becoming a Python Core Developer 83 | `_ 84 | by Emily Morehouse, January 2019 85 | * `Dial M For Mentor PyCon 2017 86 | `_ 87 | by Mariatta Wijaya, Pycon US, May 2017 88 | -------------------------------------------------------------------------------- /where_should_i_start.rst: -------------------------------------------------------------------------------- 1 | ++++++++++++++++++++++++++++++++++++++++++++ 2 | Contribute to CPython: where should I start? 3 | ++++++++++++++++++++++++++++++++++++++++++++ 4 | 5 | CPython core isn't the easiest place to start. The development process is 6 | rather enterprisy with long release cycles and rigid backwards compatibility 7 | policy. CPython also support a lot of platforms and CPU architectures. 8 | 9 | How can you start? Where? That's a hard question. CPython is old and widely 10 | used: any change must be carefully discussed to remain Python homogeneous. 11 | For bug fixes, the most complex part is the backward compatibility. 12 | 13 | It's very hard to find "easy issue". First, just **watch** the current activity 14 | to get some ideas. 15 | 16 | * To start, the best is maybe to look at recent commits to see what is 17 | currently done to get some ideas: 18 | https://github.com/python/cpython/commits/main 19 | * Look also at active bugs: see https://bugs.python.org/ homepage, and maybe 20 | the second and third pages 21 | * You may also look at ideas currently discussed on the 22 | https://mail.python.org/mailman/listinfo/python-ideas mailing list 23 | 24 | To find an easy issue, persistence is the key :-) 25 | 26 | Contribute to CPython? What is CPython? CPython is made of many parts: 27 | 28 | * CPython source code: basically made of 50% Python and 50% C code 29 | * Build system: complex tools to build Python on all platforms, Visual 30 | Studio project for Windows 31 | * Windows and macOS installer 32 | * 233,000 lines of documentation written with Sphinx 33 | * Documentation translated to multiple languages: french, japanese, and other 34 | languages 35 | * Bug tracker: bugs.python.org which has its own "meta" bug tracker for bugs in 36 | the bug tracker :-) 37 | * GitHub project: pull requests, host the Git repository 38 | * Travis CI to run the test suite on Linux and check the documentation 39 | * AppVeyor CI to run the test suite on Windows 40 | * Buildbot master and many workers to run the test suite as post-commit on 41 | many variables architectures and operating systems 42 | 43 | There are also many things around Python: 44 | 45 | * Devguide: documentation of the CPython development workflow 46 | * python-dev and python-committers mailing lists 47 | * #python-dev IRC channel 48 | * PyPI 49 | 50 | Contributing to CPython is hard and it can take up to 2 years until your work 51 | is released. Are you sure that CPython itself is the best project for you? 52 | Depending on your interests and skills, you may enjoy better to contribute 53 | to another popular project like Django or requests. 54 | 55 | Contributing to CPython is harder because CPython developers require a very 56 | high quality for contributions: every change must be carefully documented, 57 | tested and implemented. The implementation can take several rounds until it 58 | reaches the expected quality and respects a long list of requirements. 59 | 60 | Ok, I understand and I am well aware of all these things. But I want to 61 | contribute, how should I start? 62 | 63 | * Bug triage: complete bug report to adjust the title, complete the 64 | description, identify impacted Python version and impacted platforms, 65 | help to reproduce the bug, or even help to analyze and find the **root bug**. 66 | 67 | * Review pull requests: https://github.com/python/cpython/pulls/ 68 | 69 | * Make sure that a change is carefully documented. For example, behaviour 70 | changes and enhancements must have the ".. versionchanged:: x.y" markup in 71 | the documentation of the module. 72 | New features must have the ".. versionadded:: x.y" tag and maybe also 73 | documented in "What's New in Python X.Y?" documentation. 74 | * The NEWS entry and commit message must first explain the solved problem, 75 | then maybe explain the change itself. While the commit message can be 76 | technical and very detailed, the NEWS entry should be short and written 77 | for end-users who don't care of technical details. 78 | * Every change must be tested: exceptions are rare and should usually be 79 | justified. Example of exception which doesn't have to be justified: changes 80 | only impacting the documentation, changes fixing a typo in a comment. 81 | * The backward compatibility is very important. A change must be carefully 82 | reviewed to make sure that it doesn't break the backward compatibility. 83 | If it does break it, the change must be discussed with enough people 84 | to make sure that there is a smooth transition plan. 85 | * Feature removals require a DeprecationWarning in Python version N to remove 86 | it in version N+1. It's common that a feature is kept longer to avoid 87 | breaking the world just being a developer wants the perfection. 88 | Python developers must be pragmatic: balance between perfection and 89 | usability, very hard choices should be made and usually it takes a long 90 | to time to discuss them :-) 91 | * While Python 2 end of life is near (2020), Python 3 changes which make 92 | writing code working on Python 2 and Python 3 harder are usually rejected. 93 | 94 | * Propose to write a bugfix change (a pull request) for an existing bug report. 95 | This task is very hard since usually if a bug report doesn't have a patch, 96 | it's because there is a disagreement on the bug itself, or because the bugfix 97 | is very hard to implement. 98 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # Tutorial to contribute to the CPython project documentation build configuration file, created by 5 | # sphinx-quickstart on Sun Jul 16 16:31:07 2017. 6 | # 7 | # This file is execfile()d with the current directory set to its 8 | # containing dir. 9 | # 10 | # Note that not all possible configuration values are present in this 11 | # autogenerated file. 12 | # 13 | # All configuration values have a default; values that are commented out 14 | # serve to show the default. 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | # 20 | # import os 21 | # import sys 22 | # sys.path.insert(0, os.path.abspath('.')) 23 | 24 | 25 | # -- General configuration ------------------------------------------------ 26 | 27 | # If your documentation needs a minimal Sphinx version, state it here. 28 | # 29 | # needs_sphinx = '1.0' 30 | 31 | # Add any Sphinx extension module names here, as strings. They can be 32 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 33 | # ones. 34 | extensions = [] 35 | 36 | # Add any paths that contain templates here, relative to this directory. 37 | templates_path = ['_templates'] 38 | 39 | # The suffix(es) of source filenames. 40 | # You can specify multiple suffix as a list of string: 41 | # 42 | # source_suffix = ['.rst', '.md'] 43 | source_suffix = '.rst' 44 | 45 | # The master toctree document. 46 | master_doc = 'index' 47 | 48 | # General information about the project. 49 | project = 'Tutorial to contribute to the CPython project' 50 | copyright = '2017, Victor Stinner' 51 | author = 'Victor Stinner' 52 | 53 | # The version info for the project you're documenting, acts as replacement for 54 | # |version| and |release|, also used in various other places throughout the 55 | # built documents. 56 | # 57 | # The short X.Y version. 58 | version = '0.0' 59 | # The full version, including alpha/beta/rc tags. 60 | release = '0.0' 61 | 62 | # The language for content autogenerated by Sphinx. Refer to documentation 63 | # for a list of supported languages. 64 | # 65 | # This is also used if you do content translation via gettext catalogs. 66 | # Usually you set "language" from the command line for these cases. 67 | language = None 68 | 69 | # List of patterns, relative to source directory, that match files and 70 | # directories to ignore when looking for source files. 71 | # This patterns also effect to html_static_path and html_extra_path 72 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 73 | 74 | # The name of the Pygments (syntax highlighting) style to use. 75 | pygments_style = 'sphinx' 76 | 77 | # If true, `todo` and `todoList` produce output, else they produce nothing. 78 | todo_include_todos = False 79 | 80 | 81 | # -- Options for HTML output ---------------------------------------------- 82 | 83 | # The theme to use for HTML and HTML Help pages. See the documentation for 84 | # a list of builtin themes. 85 | # 86 | html_theme = 'alabaster' 87 | 88 | # Theme options are theme-specific and customize the look and feel of a theme 89 | # further. For a list of options available for each theme, see the 90 | # documentation. 91 | # 92 | # html_theme_options = {} 93 | 94 | # Add any paths that contain custom static files (such as style sheets) here, 95 | # relative to this directory. They are copied after the builtin static files, 96 | # so a file named "default.css" will overwrite the builtin "default.css". 97 | html_static_path = ['static'] 98 | 99 | 100 | # -- Options for HTMLHelp output ------------------------------------------ 101 | 102 | # Output file base name for HTML help builder. 103 | htmlhelp_basename = 'TutorialtocontributetotheCPythonprojectdoc' 104 | 105 | 106 | # -- Options for LaTeX output --------------------------------------------- 107 | 108 | latex_elements = { 109 | # The paper size ('letterpaper' or 'a4paper'). 110 | # 111 | # 'papersize': 'letterpaper', 112 | 113 | # The font size ('10pt', '11pt' or '12pt'). 114 | # 115 | # 'pointsize': '10pt', 116 | 117 | # Additional stuff for the LaTeX preamble. 118 | # 119 | # 'preamble': '', 120 | 121 | # Latex figure (float) alignment 122 | # 123 | # 'figure_align': 'htbp', 124 | } 125 | 126 | # Grouping the document tree into LaTeX files. List of tuples 127 | # (source start file, target name, title, 128 | # author, documentclass [howto, manual, or own class]). 129 | latex_documents = [ 130 | (master_doc, 'TutorialtocontributetotheCPythonproject.tex', 'Tutorial to contribute to the CPython project Documentation', 131 | 'Victor Stinner', 'manual'), 132 | ] 133 | 134 | 135 | # -- Options for manual page output --------------------------------------- 136 | 137 | # One entry per manual page. List of tuples 138 | # (source start file, name, description, authors, manual section). 139 | man_pages = [ 140 | (master_doc, 'tutorialtocontributetothecpythonproject', 'Tutorial to contribute to the CPython project Documentation', 141 | [author], 1) 142 | ] 143 | 144 | 145 | # -- Options for Texinfo output ------------------------------------------- 146 | 147 | # Grouping the document tree into Texinfo files. List of tuples 148 | # (source start file, target name, title, author, 149 | # dir menu entry, description, category) 150 | texinfo_documents = [ 151 | (master_doc, 'TutorialtocontributetotheCPythonproject', 'Tutorial to contribute to the CPython project Documentation', 152 | author, 'TutorialtocontributetotheCPythonproject', 'One line description of project.', 153 | 'Miscellaneous'), 154 | ] 155 | 156 | 157 | 158 | -------------------------------------------------------------------------------- /core_developer.rst: -------------------------------------------------------------------------------- 1 | +++++++++++++++++++++++++++++++++ 2 | What is a CPython core developer? 3 | +++++++++++++++++++++++++++++++++ 4 | 5 | Devguide: `How to Become a Core Developer 6 | `_ 7 | 8 | See `[python-committers] What is a CPython core developer? 9 | `_ 10 | (Sept 2017). 11 | 12 | python-committers 13 | ================= 14 | 15 | While the `python-committers mailing list 16 | `_ is public 17 | (anyone can read the archives), only core developers are allowed to subscribe and to 18 | send messages. 19 | 20 | Who are core developers? 21 | ======================== 22 | 23 | * `Devguide Developer Log `_ 24 | * `GitHub contributors statistics 25 | `_ gives an idea of 26 | which core developers were active recently: click on the graph to select a 27 | recent period, like last 6 months 28 | 29 | Different stages of core developers 30 | =================================== 31 | 32 | * Newcomer 33 | * Contributor: as soon as you post a comment, send an email, ask a question, 34 | you become an active contributor! 35 | * :ref:`Permission for bug triage `: once peers estimated that your 36 | behaviour is correct and that you are active, you may be proposed to be 37 | promoted to "bug triage" 38 | * :ref:`Followed by a mentor `: spotted active contributors can be asked to get a 39 | mentor to speedup their learning 40 | * :ref:`Core developer `, allowed to merge a pull request: once other core developers 41 | consider that a contributor is ready to be promoted, a core dev opens 42 | a vote on python-committers 43 | 44 | New powers but also new responsibilities 45 | ======================================== 46 | 47 | The main power of a core developer is to be allowed to merge a pull request. 48 | 49 | New powers comes with new responsibilities. Merging a pull request indirectly 50 | means becoming responsible of the added and modified code. 51 | 52 | .. _triage: 53 | 54 | Bug tracker 55 | =========== 56 | 57 | See `Helping Triage Issues `_ 58 | and `Triaging an Issue `_. 59 | 60 | Requirements to get the bug triage permission 61 | --------------------------------------------- 62 | 63 | Requirements: 64 | 65 | * Be nice, polite and respectful 66 | * Know what you are talking about, and explain your reasoning well. 67 | Contributions to the bug tracker should demonstrate an understanding of our 68 | code culture...specifically, commenting that a bug should be closed (and why) 69 | and demonstrating an understanding of what Python versions a bug applies to 70 | (enhancement versus bug fix, when to backport a bug fix and when not). See 71 | the `Status of Python branches 72 | `__ 73 | * Don't close a bug if it's not well understood to not "lose" information 74 | (closed bugs are ignored in search by default, and hidden from the main 75 | page). 76 | 77 | A good triager must be familiar with our codebase, our bug tracker, 78 | and our "code culture", in particular: 79 | 80 | * being able to find (or remember) duplicate and related issues, link 81 | them to each other, and closing the duplicates as necessary; 82 | * being able to correctly select the versions affected by the issue, 83 | the components, the stage, and other fields; 84 | * being able to verify if the issue can be reproduced and if the 85 | report is valid or not; 86 | * being able to recognize commonly reported issues and link to the 87 | appropriate FAQ or other existing issues/explanations; 88 | * being able to identify and specify the next step, possibly 89 | suggesting which files should be updated to fix the issue; 90 | * being able to locate the commits that might have introduced the 91 | issue, and the reason for the change; 92 | * being able to leave meaningful opinions on the issue (e.g. whether 93 | it should be addressed or closed and why); 94 | 95 | It usually takes some time and a few contributions before people can 96 | do these things. 97 | 98 | Responsability for bug tracker: 99 | 100 | * Request more information if a report is incomplete 101 | * Ping original reporters if they don't reply 102 | * Adjust Python version, component, bug type, etc. 103 | * Rewrite the issue title if needed 104 | * Close duplicated bugs as DUPLICATE 105 | * Close irrelevant bugs as NOTABUG 106 | 107 | Nice to have, but not a strong requirement: 108 | 109 | * Signed the CLA 110 | * At least one commit merged into CPython 111 | 112 | 113 | Give bug triage permission to a contributor 114 | ------------------------------------------- 115 | 116 | A core developer has to identify an active contributor on the bug tracker, or a 117 | contributor can also ask for more power themselves. 118 | 119 | If the contributor reaches the requirements listed in the previous section, the 120 | core developer give them triage. 121 | 122 | .. _menthor: 123 | 124 | Mentoring 125 | ========= 126 | 127 | XXX see :ref:`Getting help `. 128 | 129 | 130 | .. _core-dev: 131 | 132 | Requirements to become a core developer 133 | ======================================= 134 | 135 | "*A core dev should know not only what changes should be made, but also 136 | (and this is more important) what changes should not be made.*" 137 | -- Serhiy Storchaka 138 | 139 | The historical definition is that CPython core developer has the *commit bit*, 140 | is able to push a change to *upstream*, to the `GitHub cpython project 141 | `_. 142 | 143 | Officially, other core developers don't expect and cannot expect anything from 144 | a developer. 145 | 146 | The unwritten definition is that other core developers expect from a core 147 | developer to maintain their contributions: long term *commitment*, since 148 | CPython requires long term support: 5 years or longer. If a core developer 149 | writes a new large chunk of code but then disappears for whatever reasons, 150 | there is a risk that the code dies slowly. 151 | 152 | For example, Python branches are supported for 5 years. See the `Status of 153 | Python branches 154 | `_. 155 | 156 | Most of the following core developer requirements are already expected from 157 | regular contributors. 158 | 159 | Be nice and respectful 160 | ---------------------- 161 | 162 | Know to be nice and respectful to the others, at least to the extent 163 | they're nice and respectful to yourself :-) We don't have a rock-star (or 164 | "bro", "wizard", "ninja", whatever the hyperbole of the day is) culture here. 165 | 166 | Humility 167 | -------- 168 | 169 | Show a bit of humility towards existing work and try to understand the 170 | decisions behind something before deciding to change it all. That said, 171 | given Python's current position on the technical evolution and adoption 172 | curve, we get less and less proposals for sweeping changes (perhaps not 173 | enough, actually, since even when rejected, they help challenge the status 174 | quo). 175 | 176 | Long term commitment 177 | --------------------- 178 | 179 | When someone lands a big chunk of code, we need someone to maintain it for at 180 | least the next 2 years. Maybe for the next 10 years. 181 | 182 | It is not strictly a requirement, it's more a wish from other core developers. 183 | 184 | Reviews 185 | ------- 186 | 187 | Review patches and pull requests. While we don't require not expect 188 | newcomers to review, we expect that core developers dedicate a part of their 189 | time on reviews. What it means is that core developers care about the quality 190 | of the whole code base (and also the non-code parts), not only their own 191 | contributions to it. 192 | 193 | CPython workflow 194 | ---------------- 195 | 196 | Know the CPython workflow. Be aware of the pre-commit and 197 | post-commits CIs. How ideas are discussed. It's not only about writing and 198 | pushing patches. This part is also required from regular contributors, at 199 | least the experienced ones. 200 | 201 | CPython lifecycle 202 | ----------------- 203 | 204 | Know the project's lifecycle: Python has multiple maintained branches, some of 205 | them accept bugfixes, others only security fixes. Deciding if a fix can or 206 | cannot be backported is a complex question. 207 | 208 | Python C API specific issues 209 | ---------------------------- 210 | 211 | For C developer: know CPython specific issues like reference leaks. 212 | 213 | Good quality patches 214 | -------------------- 215 | 216 | Good quality patches: proposed changes are good (or almost good) at the first 217 | iteration. Or, if the code isn't good at the first iteration, the author is 218 | able to figure it out by themselves and doesn't rush merge it. Of course, 219 | nobody is perfect, which is why non-trivial code written by core developers 220 | ideally goes through a review phase anyway. But a general sense of what is 221 | "in good state for review/merging" vs. "just a draft I'm working on" is 222 | indeed preferable. 223 | 224 | Maintain pushed code 225 | -------------------- 226 | 227 | Pushing core means becoming responsible for this code. For 228 | regressions, backward compatibility, security, etc. 229 | 230 | Backward compatibility 231 | ---------------------- 232 | 233 | CPython has a long history and many unwritten strict rules. For example, 234 | backward compatibility is taken very seriously. We don't remove public 235 | functions in a minor release (3.x), but start with a deprecation period. It's 236 | not only about removing features, but also *changing* the behaviour. Even if 237 | Python has a wide test suite with a good code coverage, some functions are 238 | still untested, or not fully tested. 239 | 240 | Be patient 241 | ========== 242 | 243 | Be patient, being aware of Python complex code and workflow can take between 6 244 | months and 2 years. 245 | 246 | Vote to promote a contributor as a core developer 247 | ================================================= 248 | 249 | Identify a potential candidate 250 | ------------------------------ 251 | 252 | Usually the contributor doesn't ask for themselves to become a core developer, 253 | but another core developer proposes to promote them. 254 | 255 | The main questions about a potential new core developer are: 256 | 257 | * Would gaining core developer privileges improve their ability to contribute 258 | effectively (in my opinion or the opinion of another core developer)? 259 | 260 | * Do a core developer that is willing to mentor them trust their judgment on 261 | when things should be escalated for further review & discussion (or even 262 | rejected outright) versus just going ahead and merging them? 263 | 264 | Ask the candidate permission 265 | ---------------------------- 266 | 267 | The first step is to ask the contributor if they want to become a core 268 | developer. Since great power comes with great responsibilities, it's not 269 | uncommon that some contributors prefer to remain contributors. Technically, it 270 | doesn't prevent to propose pull requests, reviews, etc. 271 | 272 | Private vote 273 | ------------ 274 | 275 | If the contributor agrees, usually a *private* discussion starts. Sadly, the 276 | discussion is private because it's tricky to discuss someone skills in public. 277 | A negative vote can be harmful, whereas it isn't the intend. 278 | 279 | Sometimes, the contributor is evaluated as "too green" and someone can propose 280 | to become their mentor to help them to learn the workflow, give advices on pull 281 | requests, etc. 282 | 283 | Public vote 284 | ----------- 285 | 286 | The real vote occurs on the python-committers list where only core developers 287 | are allow to post. The developer who proposes to promote someone has to write a 288 | very short biography, list previous contributions and evaluates the contributor 289 | skills. 290 | 291 | A negative vote can still happen at this point. It doesn't mean that the 292 | contributor will never become a core dev, just that they need more practice. 293 | 294 | Vote result 295 | ----------- 296 | 297 | If the vote is positive, the contributor sends their SSH key and will be 298 | subscribed to the python-committers mailing list. 299 | 300 | Examples of public votes 301 | ------------------------ 302 | 303 | * `Proposing Carol Willing to become a core developer 304 | `_ 305 | (Brett Cannon, May 2017) 306 | * `Proposed new core developer -- Mariatta Wijaya 307 | `_ 308 | (Raymond Hettinger, January 2017) 309 | * `Promote Xiang Zhang as a core developer 310 | `_ 311 | (Victor Stinner, Nov 2016) 312 | * `commit privileges for INADA Naoki 313 | `_ 314 | (Yury Selivanov, Sept 2016) 315 | 316 | Other votes: 317 | 318 | * `commit privs given to Maciej Szulik for bugs.python.org work 319 | `_ 320 | (Brett Cannon, December 2016): https://hg.python.org/tracker/ repository 321 | 322 | Gaining Commit Privileges 323 | ------------------------- 324 | 325 | See `DevGuide: Gaining Commit Privileges 326 | `_. 327 | 328 | 329 | We Are All Volunteers 330 | ===================== 331 | 332 | Except one or two exceptions, no core developer is paid to contribute to 333 | CPython: *we are all volunteers*. Don't be surprised to not get any kind of 334 | feedback in next hours, or sometimes even before one week. 335 | 336 | Most core developers have a specific interest in specific areas of the code, 337 | and so not all core developers are interested by your specific issue. 338 | 339 | --------------------------------------------------------------------------------