Repository navigation
Add a step-by-step list (with git commands) to the pullrequest page #103
Description
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:
- Create your fork of CPython by clicking on the "Fork" button on https://github.com/python/cpython
- Create a local clone of your fork by doing
git clone https://github.com/your-username/cpython cdin thecpythondir and create a new branch withgit checkout -b branch-name- Edit the files that you want to change
- Run the tests with
./python -m testandmake patchcheck - Commit the changes with
git commit -am 'bpo-NNNNN: message' - Push the changes to your repo with
git push -u origin branch-name - Create a pull request by clicking on the "Create pull request" button
- 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.
Activity
Mariatta commentedon Feb 11, 2017
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 commentedon Feb 11, 2017
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:
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 commentedon Feb 15, 2017
I created GH-115 to address the issues with the quick start.
louisrawlins commentedon Feb 15, 2017
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:
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 commentedon Feb 15, 2017
@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 commentedon Feb 15, 2017
@brettcannon what you note is where I'm curious to get clarity:
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:
...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 commentedon Feb 15, 2017
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 commentedon Feb 15, 2017
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 commentedon Feb 15, 2017
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 commentedon Feb 15, 2017
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:
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 commentedon Feb 15, 2017
This is what I have currently for a Quick Start Guide:
* This linked documentation needs work on how to create branches, work on them, resolve conflicts, create pull request, then delete a branch.
brettcannon commentedon Feb 15, 2017
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 commentedon Feb 16, 2017
@louisrawlins Yesterday, GitHub released an open source guide on contributing and maintaining open source projects.
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 commentedon Feb 16, 2017
FWIW I think that:
louisrawlins commentedon Feb 21, 2017
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
adding pullrequest guide for python#103
Add Pull Request Step-By-Step Guide (#140)
Add Pull Request Step-By-Step Guide (python#140)
Add Pull Request Step-By-Step Guide (#140)