Making a new feature branch#

First, fetch new commits from theupstream repository:

gitfetchupstream

Then, create a new branch based on the main branch of the upstreamrepository:

gitcheckout-bmy-new-featureupstream/main

The editing workflow#

# hack hackgitstatus# Optionalgitdiff# Optionalgitaddmodified_filegitcommit# push the branch to your own Github repogitpushoriginmy-new-feature

gitpush--set-upstreamoriginmy-new-feature

gitpush

ENH:addfunctionalityXtonumpy.<submodule>.Thefirstlineofthecommitmessagestartswithacapitalizedacronym(optionslistedbelow)indicatingwhattypeofcommitthisis.Thenablankline,thenmoretextifneeded.Linesshouldn't be longer than 72characters.Ifthecommitisrelatedtoaticket,indicatethatwith"See #3456","See ticket 3456","Closes #3456"orsimilar.

API:an(incompatible)APIchangeBENCH:changestothebenchmarksuiteBLD:changerelatedtobuildingnumpyBUG:bugfixCI:continuousintegrationDEP:deprecatesomething,orremoveadeprecatedobjectDEV:developmenttoolorutilityDOC:documentationENH:enhancementMAINT:maintenancecommit(refactoring,typos,etc.)MNT:aliasforMAINTNEP:NumPyenhancementproposalsREL:relatedtoreleasingnumpyREV:revertanearliercommitSTY:stylefix(whitespace,PEP8)TST:additionormodificationoftestsTYP:statictypingWIP:workinprogress,donotmerge

Get the mailing list’s opinion#

If you plan a new feature or API change, it’s wisest to first email theNumPymailing listasking for comment. If you haven’t heard back in a week, it’sOK to ping the list again.

Asking for your changes to be merged with the main repo#

When you feel your work is finished, you can create a pull request (PR).If your changes involve modifications to the API or addition/modification of afunction, add a release note to thedoc/release/upcoming_changes/directory, following the instructions and format in thedoc/release/upcoming_changes/README.rst file.

Getting your PR reviewed#

We review pull requests as soon as we can, typically within a week. If you getno review comments within two weeks, feel free to ask for feedback byadding a comment on your PR (this will notify maintainers).

If your PR is large or complicated, asking for input on the numpy-discussionmailing list may also be useful.

Rebasing on main#

This updates your feature branch with changes from the upstream NumPyGitHub repo. If you do not absolutely need to do this, try to avoid doingit, except perhaps when you are finished. The first step will be to updatethe 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 main branchgitrebaseupstream/main

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

Finally, remove the backup branch upon a successful rebase:

gitbranch-Dtmp

Recovering from mess-ups#

Sometimes, you mess up merges or rebases. Luckily, in Git it isrelatively 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 toresolve those.

Rewriting commit history#

There’s an embarrassing typo in a commit you made? Or perhaps youmade several false starts you would like the posterity not to see.

This can be done viainteractive rebasing.

Suppose that the commit history looks like this:

gitlog--onelineeadc391Fixsomeremainingbugsa815645Modifyitsothatitworks2dec1acFixafewbugs+disable13d7934Firstimplementation6ad92e5*maskedisnowaninstanceofanewobject,MaskedConstant29001edAddpre-nepforacoupleofstructured_array_extensions....

and6ad92e5 is the last commit in themain branch. Suppose wewant to make the following changes:

• Rewrite the commit message for13d7934 to something more sensible.

• Combine the commits2dec1ac,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.#

To achieve what we want, we will make the following changes to it:

r13d7934Firstimplementationpick2dec1acFixafewbugs+disablefa815645Modifyitsothatitworksfeadc391Fixsomeremainingbugs

This means that (i) we want to edit the commit message for13d7934, and (ii) collapse the last three commits into one. Now wesave and quit the editor.

Git will then immediately bring up an editor for editing the commitmessage. After revising it, we get the output:

[detachedHEAD721fc64]FOO:Firstimplementation2fileschanged,199insertions(+),66deletions(-)[detachedHEAD0f22701]Fixafewbugs+disable1fileschanged,79insertions(+),61deletions(-)Successfullyrebasedandupdatedrefs/heads/my-feature-branch.

and the history looks now like this:

0f22701Fixafewbugs+disable721fc64ENH:Sophisticatedfeature6ad92e5*maskedisnowaninstanceofanewobject,MaskedConstant

If it went wrong, recovery is again possible as explainedabove.

Deleting a branch on GitHub#

gitcheckoutmain# delete branch locallygitbranch-Dmy-unwanted-branch# delete branch on githubgitpushorigin--deletemy-unwanted-branch

See also:https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely

Several people sharing a single repository#

If you want to work on some stuff with other people, where you are allcommitting into the same repository, or even the same branch, then justshare it via GitHub.

First fork NumPy into your account, as fromMaking your own copy (fork) of scikit-image.

Then, go to your forked repository github page, sayhttps://github.com/your-user-name/numpy

Click on the ‘Admin’ button, and add anyone else to the repo as acollaborator:

Now all those people can do:

gitclonegit@github.com:your-user-name/numpy.git

Remember that links starting withgit@ use the ssh protocol and areread-write; links starting withgit:// are read-only.

Your collaborators can then commit directly into that repo with theusual:

gitcommit-am'ENH - much better code'gitpushoriginmy-feature-branch# pushes directly into your repo

Checkout changes from an existing pull request#

If you want to test the changes in a pull request or continue the work in anew pull request, the commits are to be cloned into a local branch in yourforked repository

First ensure your upstream points to the main repo, as fromLinking your repository to the upstream repo

Then, fetch the changes and create a local branch. Assuming$ID is the pull request numberand$BRANCHNAME is the name of thenew local branch you wish to create:

git fetch upstream pull/$ID/head:$BRANCHNAME

Checkout the newly created branch:

git checkout $BRANCHNAME

You now have the changes in the pull request.

Exploring your repository#

To see a graphical representation of the repository branches andcommits:

gitk--all

To see a linear list of commits for this branch:

gitlog

Backporting#

Backporting is the process of copying new feature/fixes committed in NumPy’smain branch back to stable release branches. To do this you make a branchoff the branch you are backporting to, cherry pick the commits you want fromnumpy/main, and then submit a pull request for the branch containing thebackport.

1. First, you need to make the branch you will work on. This needs to bebased on the older version of NumPy (not main):

   # 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

2. Now you need to apply the changes from main to this branch usinggitcherry-pick:

   # Update remotegitfetchupstream# Check the commit log for commits to cherry pickgitlogupstream/main# 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

3. You might run into some conflicts cherry picking here. These areresolved the same way as merge/rebase conflicts. Except here you canusegitblame to see the difference between main and thebackported branch to make sure nothing gets screwed up.

4. Push the new branch to your Github repository:

   gitpush-uoriginbackport-3324

5. Finally make a pull request using Github. Make sure it is against themaintenance branch and not main, Github will usually suggest youmake the pull request against main.

Pushing changes to the main repo#

Requires commit rights to the main NumPy repo.

When you have a set of “ready” changes in a feature branch ready forNumPy’smain ormaintenance branches, you can pushthem toupstream as follows:

1. First, merge or rebase on the target branch.

   1. Only a few, unrelated commits then prefer rebasing:

      gitfetchupstreamgitrebaseupstream/main

      SeeRebasing on main.

   2. If all of the commits are related, create a merge commit:

      gitfetchupstreamgitmerge--no-ffupstream/main

2. Check that what you are going to push looks sensible:

   gitlog-pupstream/main..gitlog--oneline--graph

3. Push to upstream:

   gitpushupstreammy-feature-branch:main