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

[Joe Shaw]

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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/centraloh/attachments/20150316/3d76ba2c/attachment.html>