Move the "quick reference" to a dedicated page #1838
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,97 @@ | ||||||
| .. _quick-reference: | ||||||
|
|
||||||
| =============== | ||||||
| Quick Reference | ||||||
|
Member
There was a problem hiding this comment. Use sentence case for headers: https://devguide.python.org/documentation/style-guide/#capitalization
Suggested change
Collaborator
There was a problem hiding this comment. May make sense to be more specific on the title of this doc. Quick reference feels too broad. Something that evokes the original purpose checklist/cheatsheet would make more sense.
Author
There was a problem hiding this comment. We could put it at or near the end of Getting Started, under the name "Workflow cheatsheet". It would read logically that way, and that name is harmonious with the element of this doc that I'm trying to preserve. |
||||||
| =============== | ||||||
|
|
||||||
| Here are the basic steps needed to get set up and open a pull request. | ||||||
|
|
||||||
| This is meant as a checklist and cheat-sheet, not a comprehensive guide. | ||||||
| For complete instructions please see the :ref:`setup guide <setup>`. | ||||||
|
Member
There was a problem hiding this comment. I don't think this makes sense now, we redirect people back to the page they've just read?
Member
There was a problem hiding this comment. This doesn't go back to the home page. It goes to a detailed page about git etc.
Member
There was a problem hiding this comment. I was not referring to the home page. As @sirosen noted in the PR description:
We're sending them back to the page just before.
Member
There was a problem hiding this comment. I see, sorry. So we should move this up in the contents.
Member
There was a problem hiding this comment. I think we can rename it to "Overview," and make it an index for the overall quite long "Getting started" section. Additionally, we could merge it with the other Quick Guide, and add a link to the Where to get help at the end. Some of the steps could also use additional links to the more detailed sections.
Collaborator
There was a problem hiding this comment. I would love to see this page be minimalist visually and cheatsheet-like. I think @StanFromIreland is on the right track though "Overview" feels too broad.
Author
There was a problem hiding this comment.
Oh no! I didn't realize that there was another, other-other quick reference. 😂 My initial reaction is that I think these should be combined, still in the form of a new page. I need to do some careful cross-comparison of the content and see if such a change is feasible in practice, without this PR growing too large in scope. |
||||||
|
|
||||||
| 1. Install and set up :ref:`Git <vcsetup>` and other dependencies | ||||||
| (see the :ref:`Git Setup <setup>` page for detailed information). | ||||||
|
|
||||||
| 2. Fork `the CPython repository <https://github.com/python/cpython>`__ | ||||||
| to your GitHub account and :ref:`get the source code <checkout>` using:: | ||||||
|
|
||||||
| git clone https://github.com/<your_username>/cpython | ||||||
| cd cpython | ||||||
|
|
||||||
| 3. Build Python: | ||||||
|
|
||||||
| .. tab:: Unix | ||||||
|
|
||||||
| .. code-block:: shell | ||||||
|
|
||||||
| ./configure --config-cache --with-pydebug && make -j $(nproc) | ||||||
|
|
||||||
| .. tab:: macOS | ||||||
|
|
||||||
| .. code-block:: shell | ||||||
|
|
||||||
| ./configure --config-cache --with-pydebug && make -j8 | ||||||
|
|
||||||
| .. tab:: Windows | ||||||
|
|
||||||
| .. code-block:: dosbatch | ||||||
|
|
||||||
| PCbuild\build.bat -e -d | ||||||
|
|
||||||
| See also :ref:`more detailed instructions <compiling>`, | ||||||
|
Member
There was a problem hiding this comment. All of the above steps should have been completed by the time they reach this page, so we don't quite need them.
Collaborator
There was a problem hiding this comment. I think all the "see also" items could go later in this document. Perhaps in a "Dive deeper" section. |
||||||
| :ref:`how to install and build dependencies <build-dependencies>`, | ||||||
| and the platform-specific pages for :ref:`Unix <unix-compiling>`, | ||||||
| :ref:`macOS <macOS>`, and :ref:`Windows <windows-compiling>`. | ||||||
|
|
||||||
| 4. :ref:`Run the tests <runtests>`: | ||||||
|
|
||||||
| .. tab:: Unix | ||||||
|
|
||||||
| .. code-block:: shell | ||||||
|
|
||||||
| ./python -m test -j3 | ||||||
|
|
||||||
| .. tab:: macOS | ||||||
|
|
||||||
| .. code-block:: shell | ||||||
|
|
||||||
| ./python.exe -m test -j8 | ||||||
|
|
||||||
| .. note:: | ||||||
| :ref:`Most <mac-python.exe>` macOS systems use | ||||||
| :file:`./python.exe` in order to avoid filename conflicts with | ||||||
| the ``Python`` directory. | ||||||
|
|
||||||
| .. tab:: Windows | ||||||
|
|
||||||
| .. code-block:: dosbatch | ||||||
|
|
||||||
| .\python.bat -m test -j3 | ||||||
|
|
||||||
| 5. Create a new branch where your work for the issue will go, for example:: | ||||||
|
Member
There was a problem hiding this comment. This section is duplicated by our other "Quick guide".
Collaborator
There was a problem hiding this comment. Steps 5-7 could be their own section or their own page. Keep 1-4 as build from source and run tests. |
||||||
|
|
||||||
| git checkout -b fix-issue-12345 main | ||||||
|
|
||||||
| If an issue does not already exist, please `create it | ||||||
| <https://github.com/python/cpython/issues>`__. Trivial issues (for example, typos) do | ||||||
| not require an issue. | ||||||
|
|
||||||
| 6. Push the branch on your fork on GitHub and :ref:`create a pull request | ||||||
| <pullrequest>`. Include the issue number using ``gh-NNNNNN`` in the | ||||||
| pull request title. For example: | ||||||
|
|
||||||
| .. code-block:: text | ||||||
|
|
||||||
| gh-12345: Fix some bug in spam module | ||||||
|
|
||||||
| 7. Add a News entry into the ``Misc/NEWS.d/`` directory as individual file. The | ||||||
| news entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`__, | ||||||
| or the :pypi:`blurb` tool and its ``blurb add`` | ||||||
| command. Please read more about ``blurb`` in its | ||||||
| `repository <https://github.com/python/blurb>`__. | ||||||
|
|
||||||
| .. note:: | ||||||
|
|
||||||
| First time contributors will need to sign the Contributor Licensing | ||||||
| Agreement (CLA) as described in the :ref:`Licensing <cla>` section of | ||||||
| this guide. | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if it would be better to move this before setup-building. I think we might want to rethink the name "Quick reference". The original text was created to be a checklist/cheatsheet for getting started quickly especially at sprints.
I don't object to making a separate doc for the content. I would leave a clear link/callout in the index page at the same place in the text so that folks who have the page bookmarked for this content know where it moved.