Simplify documentation between setup guide and boot camp

@ezio-melotti

Having all the commands here is convenient, since people doing a setup don't have to follow links back and forth from this page to the GitHub bootcamp page. On the other hand, the bootcamp entries are also convenient on their own ¹.

I think the best approach would be to:

list all upstream-related commands in a single step and code block², with short inline comments (about what the commands do)
have the same commands in the bootcamp, but with more in-depth discussions (e.g. why they are necessary)
from here, link to the bootcamp so that people that want more details can find them there
add a couple of comments about the duplicated commands as a remainder for people updating either page

Originally posted by @ezio-melotti in #943 (comment)

I regular revisit the entry about setting up a remote, since I do it for every new repo I clone, but not often enough that I remember the exact syntax ↩
this includes steps 6-9. Step 5 can be separated. ↩

Can I take this as my first PR? Could you please guide me on where to start? I would need exact pointers for [1] and [2].

Most of this is already implemented.
In https://devguide.python.org/getting-started/setup-building/#get-the-source-code I would remove items 7 and 8 (so that they are included under 6), then combine their sentences and their examples, so that the end result looks like:

...

Add an upstream remote, then configure git to pull main from upstream and always push to origin:

$ cd cpython
$ git remote add upstream https://github.com/python/cpython
$ git config --local branch.main.remote upstream
$ git remote set-url --push upstream git@github.com:<your-username>/cpython.git

Verify that your setup is correct:

$ git remote -v
...

For more information about these commands see <link to the bootcamp>.

Then you can add an rst comment both here and in the bootcamp page, to mention that these commands are duplicated, so that whoever ends up editing one knows that they should update the other too.

I didn't get the following point. Please bear with me, I am new at this and understand how frustrating it might be to explain little things to beginners.

Then you can add an rst comment both here and in the bootcamp page, to mention that these commands are duplicated, so that whoever ends up editing one knows that they should update the other too.

I am creating a PR.

Then you can add an rst comment both here and in the bootcamp page, to mention that these commands are duplicated,

I believe Ezio means that we need to add a comment, and using reStructuredText's comment markup to do it.

The comment is about the fact the commands are duplicated, and to add these comments to both the "setup-building" page and to the "git bootcamp" page.

To add a comment in restructuredText, you'd start a line with two dots

.. This text is a comment 

..
   This is a comment too

This is not a comment

@Mariatta

@Mariatta Thank you. I figured it out and made my first real open-source PR. Please let me know if there are things that I can improve.

Navigation Menu

Repository navigation

Simplify documentation between setup guide and boot camp #964

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Simplify documentation between setup guide and boot camp #964

Description

Footnotes

Activity

abdnafees commented on Nov 14, 2022

ezio-melotti commented on Nov 14, 2022

abdnafees commented on Nov 15, 2022

abdnafees commented on Nov 15, 2022

Mariatta commented on Nov 15, 2022

abdnafees commented on Nov 15, 2022

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions