Add a step-by-step list (with git commands) to the pullrequest page

[ezio-melotti]

The pullrequest page should include a step-by-step list with the required git commands required to create a pull request.

The list should be something like:

1. Create your fork of CPython by clicking on the "Fork" button on https://github.com/python/cpython
2. Create a local clone of your fork by doing git clone https://github.com/your-username/cpython
3. cd in the cpython dir and create a new branch with git checkout -b branch-name
4. Edit the files that you want to change
5. Run the tests with ./python -m test and make patchcheck
6. Commit the changes with git commit -am 'bpo-NNNNN: message'
7. Push the changes to your repo with git push -u origin branch-name
8. Create a pull request by clicking on the "Create pull request" button
9. Add a comment and submit the pull request.

The list can include links to relevant sections (e.g. how to run the tests) and mention that the first two steps are optional. Instead of a list, something like the following is also ok:

# clone your fork of CPython
git clone https://github.com/your-username/cpython
cd cpython
# create new branch
git checkout -b branch-name
# edit the files you want to change and run the tests
./python -m test
# check the patch
make patchcheck
# commit the changes
git commit -am 'bpo-NNNNN: message'
# push them to your fork
git push -u origin branch-name

This can be prefixed by a paragraph explaining how to create your own fork, and followed by one that explains how to create the PR after the push.

Also note that there's some overlapping with the committing page that also includes some command and some steps that should be included in this list (e.g. the minimal configuration and initial setup). I think it would be better to have everything in a single page with additional subsections for core-devs-specific steps.

[Mariatta]

Thanks @ezio-melotti :)

I think we should also update the Getting Setup page to include instructions to first fork the repo, instead of cloning the official cpython repo.

https://cpython-devguide.readthedocs.io/setup.html#getting-the-source-code

Step 2 of Quick Start guide should also be updated https://cpython-devguide.readthedocs.io/index.html
I think it will be confusing when people cloned the official cpython repo in step 2, but then we're told to fork it in step 5 when making pull request.

What do you think?

[ezio-melotti]

I agree on both points. Some sections and commands have been converted directly from hg to git, but the current workflow doesn't fit the previous structure anymore, so I think we should reorganize things a bit.

The Getting Set Up section should also include the info that are currently in the Minimal Configuration section and in Remotes Setup/Configuration.

The quick-start should provide a general overview without entering too much in the details, so it should be something like:

1. Install and set up dependencies like git
2. Fork python/cpython and get a local clone of your fork
3. Build Python and run the tests
4. Create a new branch and make your changes
5. Run the tests and commit
6. Push the branch, and create a pull request
7. Create an issue if one doesn't already exist

And then link to specific sections/pages with more detailed information.
Perhaps updating the quick start should become a separate issue.

Disclaimer: I still have to get familiar with the new workflow and go through the updated devguide and get an idea of all the parts and see if they can be organized better, so take this with a grain of salt.

[ezio-melotti]

I created GH-115 to address the issues with the quick start.

[louisrawlins]

Hi @Mariatta and @ezio-melotti

I'm new to the breadth of documentation for CPython, and I haven't run it myself yet. But, I thought I'd offer some thoughts and take an attempt to help organize the quick-start list (since it's meant for people like myself who haven't had a chance to build CPython, make changes, etc).

A point that kept sticking to me before contributing was trying to remember the difference between a Clone and a Fork. There is a decent conversation about how a Fork is a concept limited to Github with some benefits over Cloning:

http://stackoverflow.com/questions/6286571/are-git-forks-actually-git-clones

I'm not sure if contributors are limited to submitting Pull Requests from Forks only, or it they could just as easily clone CPython, push a branch to their local repo, then link back to that branch for the Pull Request.

---

From your conversation, I'm seeing the Quick Start Guide to look something like:

1. Get started and set up your system

2. Fork CPython on Github (using the button in the upper-right on Github)

3. Compile Python on your system

4. Run tests after you have built Python

5. Add an "upstream" Remote in Git on your system

6. Create a Branch in Git where you can work on changes ---This needs some more elaboration about how to create branches, work on them, resolve conflicts, create pull request, then delete branch.---

7. Run tests again

8. Commit changes and resolve conflicts in Git

9. Push commits to your Github repo

10. Submit a Pull Request and reference the branch you worked in on your fork

11. Create an issue that describes your change, if one doesn't exist

12. Celebrate! You just contributed to Python. :)

Because there are several ways to create, commit and share changes to the CPython source code, this guide only covers popular defaults.

Am I missing steps or adding some that are unnecessary?

Here is another source I found useful recently:

https://gist.github.com/Chaser324/ce0505fbed06b947d962

[brettcannon]

@louisrawlins Based on your "push a branch to their local repo" question, I don't see any step of how the branch you created gets on to internet for anyone to see (let alone on to GitHub for people to create a pull request from).

And forking actually has nothing directly to do with cloning. A fork on GitHub is nothing more than GitHub making a copy of a repository and placing it under your account. The idea is that your fork/copy of the original repository is there for you to work/play with as you see fit. And if you make a branch that has changes you want to see lean upstream in the project your forked/copied from, then you push your branch to GitHub in your fork/copy and then create a pull request for it.

[louisrawlins]

@brettcannon what you note is where I'm curious to get clarity:

The idea is that your fork/copy of the original repository is there for you to work/play with as you see fit. And if you make a branch that has changes you want to see lean upstream in the project your forked/copied from, then you push your branch to GitHub in your fork/copy and then create a pull request for it.

Outside of Github, if I were to make a clone of CPython and create a new branch -- can I create a Pull Request?

It's definitely an extra-step to clone from Github, then push a repo back up to Github rather than forking the repo. My curiosity is whether that is a valid workflow or something similar to what you guys were doing with hg.

On Stackoverflow, someone makes mention:

To me, the key point is that you can't submit a PR from your local copy unless you're declared to be a contributor. I'm so used to submitting PRs from my local repo, but that's because I'm always marked as a contributor. If you think about it, to submit a PR you have to push a branch to the remote repo and then create the PR. I guess it makes sense if you don't want random people creating branches on your repo. And that you'd prefer them to fork it and submit PRs that way instead. – Adam Zerner Feb 22 '16 at 1:18

...which is what got me thinking about this in the first place.

It sounds to me like it's such a custom case that we can assume the contributor might not need the Quick Start Guide.

[brettcannon]

You can only create a pull request if the branch exists somewhere on GitHub. Otherwise you have to create a patch file and upload it to the issue tracker.

[louisrawlins]

Gotcha. Thanks. It's the third way that I keep forgetting.

Contribution looks like:
1a. Create Pull Request in Github to merge a branch from your Fork
1b. Create Pull Request in Github to merge a branch from your Cloned Repository
1c. Upload Patch to bugs.python.org

Is that a fair representation at a broad level?

[brettcannon]

1b doesn't work; if you didn't fork on GitHub then it has no way of knowing that your repo is supposed to somehow come from the cpython repo.

[louisrawlins]

Okay. After some convoluted cloning and branching, I see what you're talking about.

When you select "New Pull Request" from the CPython repo, you're prompted to find it either from the branches within that repo, or a forked repository:

Compare changes across branches, commits, tags, and more below. If you need to, you can also compare across forks.

My branch from cloned CPython won't show up in Github for a Pull Request to CPython unless I've forked it from the original CPython repo and made another branch from forked CPython.

Conceptually, it makes sense, but I wanted to ensure there wasn't another way to approach Pull Requests on Github.

[louisrawlins]

This is what I have currently for a Quick Start Guide:

1. Get started and set up your system

2. Fork CPython on Github (using the Fork button in the upper-right on Github)

3. Compile Python on your system

4. Run tests after you have built Python

5. Add an "upstream" Remote in Git on your system

6. Create a Branch in Git where you can work on changes *

7. Run tests again

8. Commit changes and resolve conflicts in Git

9. Push commits to your Github repo

10. Contribute your changes
    10a. Create Pull Request in Github to merge a branch from your Fork
    10b. Upload Patch to bugs.python.org

11. Create an Issue that describes your change, if one doesn't exist

12. Celebrate! You just contributed to Python. :)

Because there are several ways to create, commit and share changes to the CPython source code, this guide only covers popular defaults.

 * This linked documentation needs work on how to create branches, work on them, resolve conflicts, create pull request, then delete a branch.

[brettcannon]

Does step 2 include cloning your fork? I would also move step 5 up to be immediate after cloning. I think step 7 should move after step 8. As for step 10b, it can be mentioned but should not be emphasized. And step 11 should be the first thing if you're explicitly working on something -- so if you're just exploring then it can be step 6 -- to make sure that someone else doesn't also start working on it.

[willingc]

@louisrawlins Yesterday, GitHub released an open source guide on contributing and maintaining open source projects.

• Main open source guide landing page
• Site on contributing to open source
• Section on how to contribute including the typical GitHub workflow

The steps are pretty well outlined in the docs here. It would likely make sense to link to some of these resources as well.

FYI @Mariatta @brettcannon

[ezio-melotti]

FWIW I think that:

• the quick start should be short and outline the main steps only;
• the quick start should link to other devguide pages that describe the steps in greater detail (including the detailed steps, alternatives, how to deal with issues and exceptions, etc);
• by following the quick start and the internal links, one should be able to do everything from setting up to having the PR merged, without having to leave the devguide, and with no prior knowledge of Git/GitHub/bpo;
• the devguide doesn't necessarily have to explain in detail each commands, but should at least list them all;

[louisrawlins]

Hey ya'll. Thanks for the great feedback. Hope you had nice weekends.

Here are incorporated edits:

https://github.com/louisrawlins/devguide/wiki/pullrequest.html%23quick-guide

I've split off "3.1.5. Quick Guide Step-by-step" because I'm not quite sure where it belongs. We now have commands and links to documentation which are fine to interleave, but they felt a little clearer when separated.

I'm generously borrowing the contributors workflow from a project I worked on years back, because it felt similar to CPython. If it feels off-base in any way, just let me know.

If things look decent, I can start arranging edits to the devguide.

Peace & thank you @ezio-melotti @willingc @brettcannon @Mariatta