Make some changes. When you feel that you’ve made a complete, working set
of related changes, move on to the next steps.

Optional: Check which files have changed with gitstatus (see git
status). You’ll see a listing like this one:

# On branch my-new-feature# Changed but not updated:# (use "git add <file>..." to update what will be committed)# (use "git checkout -- <file>..." to discard changes in working directory)## modified: README## Untracked files:# (use "git add <file>..." to include in what will be committed)## INSTALLnochangesaddedtocommit(use"git add"and/or"git commit -a")

Optional: Compare the changes with the previous version using with gitdiff (git diff). This brings up a simple text browser interface that
highlights the difference between your files and the previous version.

Add any relevant modified or new files using gitaddmodified_file
(see git add). This puts the files into a staging area, which is a queue
of files that will be added to your next commit. Only add files that have
related, complete changes. Leave files with unfinished changes for later
commits.

To commit the staged files into the local copy of your repo, do gitcommit. At this point, a text editor will open up to allow you to write a
commit message. Read the commit message
section to be sure that you are writing a
properly formatted and sufficiently detailed commit message. After saving
your message and closing the editor, your commit will be saved. For trivial
commits, a short commit message can be passed in through the command line
using the -m flag. For example, gitcommit-am"ENH:Somemessage".

In some cases, you will see this form of the commit command: gitcommit-a. The extra -a flag automatically commits all modified files and
removes all deleted files. This can save you some typing of numerous gitadd commands; however, it can add unwanted changes to a commit if you’re
not careful. For more information, see why the -a flag? - and the
helpful use-case description in the tangled working copy problem.

Assuming you have followed the instructions in these pages, git will create
a default link to your github repo called origin. In git >= 1.7 you
can ensure that the link to origin is permanently set by using the
--set-upstream option:

gitpush--set-upstreamoriginmy-new-feature

From now on git will know that my-new-feature is related to the
my-new-feature branch in your own github repo. Subsequent push calls
are then simplified to the following:

gitpush

You have to use --set-upstream for each new branch that you create.

It may be the case that while you were working on your edits, new commits have
been added to upstream that affect your work. In this case, follow the
Rebasing on master section of this document to apply those changes to
your branch.

Describing the motivation for a change, the nature of a bug for bug fixes or
some details on what an enhancement does are also good to include in a commit
message. Messages should be understandable without looking at the code
changes. A commit message like MAINT:fixedanotherone is an example of
what not to do; the reader has to go look for context elsewhere.

When you feel your work is finished, you can create a pull request (PR). Github
has a nice help page that outlines the process for filing pull requests.

If your changes involve modifications to the API or addition/modification of a
function, you should initiate a code review. This involves sending an email to
the NumPy mailing list with a link to your PR along with a description of
and a motivation for your changes.

This updates your feature branch with changes from the upstream NumPy
github repo. If you do not absolutely need to do this, try to avoid doing
it, except perhaps when you are finished. The first step will be to update
the remote repository with new commits from upstream:

gitfetchupstream

Next, you need to update the feature branch:

# go to the feature branchgitcheckoutmy-new-feature# make a backup in case you mess upgitbranchtmpmy-new-feature# rebase on upstream master branchgitrebaseupstream/master

If you have made changes to files that have changed also upstream,
this may generate merge conflicts that you need to resolve. See
below for help in this case.

Finally, remove the backup branch upon a successful rebase:

gitbranch-Dtmp

Note

Rebasing on master is preferred over merging upstream back to your
branch. Using gitmerge and gitpull is discouraged when
working on feature branches.

Sometimes, you mess up merges or rebases. Luckily, in Git it is
relatively straightforward to recover from such mistakes.

If you mess up during a rebase:

gitrebase--abort

If you notice you messed up after the rebase:

# reset branch back to the saved pointgitreset--hardtmp

If you forgot to make a backup branch:

# look at the reflog of the branchgitreflogshowmy-feature-branch8630830my-feature-branch@{0}:commit:BUG:io:closefilehandlesimmediately278dd2amy-feature-branch@{1}:rebasefinished:refs/heads/my-feature-branchonto11ee694744f2552d26aa21amy-feature-branch@{2}:commit:BUG:lib:makeseek_gzip_factorynotleakgzipobj...# reset the branch to where it was before the botched rebasegitreset--hardmy-feature-branch@{2}

If you didn’t actually mess up but there are merge conflicts, you need to
resolve those. This can be one of the trickier things to get right. For a
good description of how to do this, see this article on merging conflicts.

and 6ad92e5 is the last commit in the master branch. Suppose we
want to make the following changes:

Rewrite the commit message for 13d7934 to something more sensible.

Combine the commits 2dec1ac, a815645, eadc391 into a single one.

We do as follows:

# make a backup of the current stategitbranchtmpHEAD# interactive rebasegitrebase-i6ad92e5

This will open an editor with the following text in it:

pick13d7934Firstimplementationpick2dec1acFixafewbugs+disablepicka815645Modifyitsothatitworkspickeadc391Fixsomeremainingbugs# Rebase 6ad92e5..eadc391 onto 6ad92e5## Commands:# p, pick = use commit# r, reword = use commit, but edit the commit message# e, edit = use commit, but stop for amending# s, squash = use commit, but meld into previous commit# f, fixup = like "squash", but discard this commit's log message## If you remove a line here THAT COMMIT WILL BE LOST.# However, if you remove everything, the rebase will be aborted.#

Backporting is the process of copying new feature/fixes committed in
numpy/master back to stable release branches. To do this you make a branch
off the branch you are backporting to, cherry pick the commits you want from
numpy/master, and then submit a pull request for the branch containing the
backport.

First, you need to make the branch you will work on. This needs to be
based on the older version of NumPy (not master):

# Make a new branch based on numpy/maintenance/1.8.x,# backport-3324 is our new name for the branch.gitcheckout-bbackport-3324upstream/maintenance/1.8.x

Now you need to apply the changes from master to this branch using
git cherry-pick:

# Update remotegitfetchupstream# Check the commit log for commits to cherry pickgitlogupstream/master# This pull request included commits aa7a047 to c098283 (inclusive)# so you use the .. syntax (for a range of commits), the ^ makes the# range inclusive.gitcherry-pickaa7a047^..c098283...# Fix any conflicts, then if needed:gitcherry-pick--continue

You might run into some conflicts cherry picking here. These are
resolved the same way as merge/rebase conflicts. Except here you can
use git blame to see the difference between master and the
backported branch to make sure nothing gets screwed up.

Push the new branch to your Github repository:

gitpush-uoriginbackport-3324

Finally make a pull request using Github. Make sure it is against the
maintenance branch and not master, Github will usually suggest you
make the pull request against master.