Recommended Git Workflow

You don't have to do it this way, but it makes working with remote repositories easier on you and merging your work easier on us.

We use the "Fork + Pull" model of development wherein you work in your own copy of the repository (the fork) and we pull your changes in.

If you get confused, let us know and we can help. Stack Overflow is another great place for getting git help. If working with git gets to be too frustrating, we will always accept normal patches. We'd rather have you submitting patches than fighting git.

Repository Setup

First, fork and clone https://github.com/schwern/perl5i normally.
See http://help.github.com/fork-a-repo/ for instructions.

# Add schwern's repository as a remote called "upstream"
git remote add upstream git://github.com/schwern/perl5i.git

# Fetch schwern's repository
git fetch upstream

# Set your master to track upstream/master
# Not necessary for this example, but helpful.
git branch --set-upstream master upstream/master

# Make sure your master is up to date
# Also not strictly necessary, but helpful
git pull upstream

--set-upstream was added in git 1.7. If you're using an earlier git you'll have to set your branch config manually.

# Set your master to track upstream/master
git config branch.master.remote upstream
git config branch.master.merge refs/heads/master

Feature branch management

For each issue you work on, do not work in the master branch. Make your own branch for each issue. This will keep your work untangled and allow you to work on multiple issues at once.

# Branch off of the upstream master, not yours
git checkout -b issue/123 upstream/master

# You're now in a local feature branch tracking upstream/master
# Work normally, commit often
...work work work...

# When you commit, please mention the issue number in the commit message
# Like "For #123".

# Get updates from upstream
# --rebase explained below
# I have this aliased to "repull" in my .gitconfig
git pull --rebase

...fix conflicts...
...work work work...

# Get more updates
git pull --rebase

...fix conflicts...
...work work work DONE!

# One last check for updates
git pull --rebase

...fix conflicts...

# Run the whole test suite
prove -lr t

# Push your branch to Github
git push origin issue/123

Issue a pull request on Github.
See http://help.github.com/send-pull-requests/ for instructions. 
Remember to go to Branches and select your branch before trying to send the pull request.

Branching off upstream/master instead of your master means you can update in one step (git pull) instead of two (first pull from upstream to origin and then from origin to your branch).

If you're comfortable with it, I would recommend a rebase/pull (git pull --rebase)to update your branch with my changes rather than the normal merge/pull. This will provide a cleaner and easier to review history. If you're not comfortable, just use git pull and we'll cope with the extra merge points.