[CentralOH] Help with doing git pull requests on a Python project

Tue Mar 31 15:43:16 CEST 2015

All right! Congratulations Nick!

On Mon, Mar 30, 2015 at 11:25 PM Nick Albright <nick.albright at gmail.com>
wrote:

> Joe!
>
> Thanks for the wonderful write up!  I just used it to create a pull
> request for an open source project! = )
>  -Nick
> On Mon, Mar 16, 2015 at 9:46 AM, Joe Shaw <joe at joeshaw.org> wrote:
>
>> Hi,
>>
>> The problem with those pandas instructions is that they don't tell the
>> whole story of what you need to do.
>>
>> The basic workflow for contributing to a project on GitHub is:
>>
>>    1. Clone the project you want to work on
>>    2. Fork the project you want to work on
>>    3. Create a *feature branch* to do your own work in
>>    4. Commit your changes to your feature branch
>>    5. Push your feature branch to your fork on GitHub
>>    6. Send a pull request for your branch on your fork into the upstream
>>    mainline
>>
>> A very helpful tool for interacting with GitHub is the hub tool, which
>> can either be used as a stand-in replacement for git or as a separate
>> tool.
>>
>> https://github.com/github/hub
>>
>> It abstracts away a lot of the annoying parts of interacting with Git and
>> forks and such.  I'll try to do step by step through the process, using the
>> hub and git command-line tools.
>>
>> *Clone the project you want to work on*
>>
>> $ hub clone pydata/pandas
>>
>> (Equivalent to git clone https://github.com/pydata/pandas.git)
>>
>> This clones the project from the server onto your local machine.  When
>> working in git you make changes to your local copy of the repository.  Git
>> has a copy of *remotes* which are, well, remote copies of the
>> repository.  When you clone a new project, a remote called origin is
>> automatically created that points to the repository you provide in the
>> command line above.  In this case, pydata/pandas on GitHub.
>>
>> When you are ready to upload your changes back to the main repository,
>> you *push to the remote*.  Between when you cloned and now changes may
>> have been made to upstream remote repository.  To get those changes, you *pull
>> from the remote*.
>>
>> *Fork the project you want to work on*
>>
>> The easiest way to do this is with hub.  Make sure to run this command
>> from the pandas directory that was created when you cloned the repo.
>>
>> $ hub fork
>>
>> This does a couple of things.  It creates a fork of pandas in your GitHub
>> account.  It establishes a new remote in your local repository with the
>> name of your github username.  So in my case I now have two remotes:
>> origin, which points to the main upstream repository; and joeshaw, which
>> points to my forked repository.  We'll be pushing to my fork.
>>
>> *Create a feature branch to do your own work in*
>>
>> This creates a place to do your work in that is separate from the main
>> code.
>>
>> $ git checkout -b doc-work
>>
>> doc-work is what I'm choosing to name this branch.  You can name it
>> whatever you like.  Hyphens are idiomatic.
>>
>> Now do whatever changes you are going to do for this project.
>>
>> *Commit your changes to your feature branch*
>>
>> If you are creating new files, you will need to explicitly add them to
>> the to-be-commited list (also called the index, or staging area):
>>
>> $ git add file1.md file2.md etc
>>
>> If you are just editing existing files, you can add them all in one batch:
>>
>> $ git add -u
>>
>> Next you need to commit the changes.
>>
>> $ git commit
>>
>> This will bring up an editor where you type in your commit message.  The
>> convention is usually to type a short summary in the first line (50-60
>> characters max), then a blank line, then additional details if necessary.
>>
>> *Push your feature branch to your fork in GitHub*
>>
>> Ok, remember that your fork is a remote named after your github
>> username.  In my case, joeshaw.
>>
>> $ git push joeshaw doc-work
>>
>> This pushes to the joeshaw remote only the doc-work branch.  Now your
>> work is publicly visible to anyone on your fork.
>>
>> *Send a pull request for your branch on your fork into the upstream
>> mainline*
>>
>> You can do this either on the web site or using the hub tool again.
>>
>> $ hub pull-request
>>
>> This will open your editor again.  If you only had one commit on your
>> branch, the message for the pull request will be the same as the commit.
>> This might be good enough, but you might want to elaborate on the purpose
>> of the pull request.  Like commits, the first line is a summary of the pull
>> request and the other lines are the body of the PR.
>>
>> In general you will be requesting to pull from your current branch (in
>> this case doc-work) into the master branch of the origin remote.
>>
>> If your pull request is accepted as-is, the maintainer will merge it into
>> the official upstream sources.  Good luck!
>>
>> This isn't an exhaustive tutorial, but hopefully it's enough to get you
>> started and contributing.  I hope you find it useful.
>>
>> Joe
>>
>>
>>
>>
>>
>> On Sun, Mar 15, 2015 at 12:50 PM, pybokeh <pybokeh at gmail.com> wrote:
>>
>>> Hello List,
>>> I took a basic git/github class a while back, but I'm still struggling.
>>> I only know how to create my own repositories locally and at github and
>>> push changes to them and raise issues.  But that's about it since I don't
>>> really create code that would be used by others and my level of Python is
>>> not that great to be able to contribute to the actual source code of Python
>>> projects.  However, I can contribute at least by improving documentation.
>>> I want to improve documentation of a Python project and was wondering if
>>> someone could meet me at this week's upcoming dojo meeting this Friday or I
>>> can meet at other times of the week.  Coffee, tea, or snacks on me.
>>>
>>> I was provided this link on how to contribute to this particular project
>>> ("pandas"):
>>> https://github.com/pydata/pandas/wiki/Contributing
>>>
>>> and that's where things got confusing for me and need help with.
>>>
>>> If you can spare some time with me, I'd really appreciate it.  Thanks!
>>>
>>> - Daniel
>>>
>>> _______________________________________________
>>> CentralOH mailing list
>>> CentralOH at python.org
>>> https://mail.python.org/mailman/listinfo/centraloh
>>>
>>>
>>
>> _______________________________________________
>> CentralOH mailing list
>> CentralOH at python.org
>> https://mail.python.org/mailman/listinfo/centraloh
>>
>> _______________________________________________
> CentralOH mailing list
> CentralOH at python.org
> https://mail.python.org/mailman/listinfo/centraloh
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/centraloh/attachments/20150331/42835726/attachment.html>