diff options
Diffstat (limited to 'doc/source/dev/gitwash')
| -rw-r--r-- | doc/source/dev/gitwash/development_setup.rst | 4 | ||||
| -rw-r--r-- | doc/source/dev/gitwash/development_workflow.rst | 73 | ||||
| -rw-r--r-- | doc/source/dev/gitwash/following_latest.rst | 2 | ||||
| -rw-r--r-- | doc/source/dev/gitwash/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/dev/gitwash/patching.rst | 132 |
5 files changed, 67 insertions, 145 deletions
diff --git a/doc/source/dev/gitwash/development_setup.rst b/doc/source/dev/gitwash/development_setup.rst index 0cff3c214..adfe700e2 100644 --- a/doc/source/dev/gitwash/development_setup.rst +++ b/doc/source/dev/gitwash/development_setup.rst @@ -2,6 +2,10 @@ Getting started with Git development ==================================== +This section and the next describe in detail how to set up git for working +with the NumPy source code. If you have git already set up, skip to +:ref:`development-workflow`. + Basic Git setup ############### diff --git a/doc/source/dev/gitwash/development_workflow.rst b/doc/source/dev/gitwash/development_workflow.rst index 75de6ae67..8606b9018 100644 --- a/doc/source/dev/gitwash/development_workflow.rst +++ b/doc/source/dev/gitwash/development_workflow.rst @@ -16,7 +16,8 @@ Basic workflow In short: -1. Start a new *feature branch* for each set of edits that you do. +1. Update your ``master`` branch if it's not up to date. + Then start a new *feature branch* for each set of edits that you do. See :ref:`below <making-a-new-feature-branch>`. Avoid putting new commits in your ``master`` branch. @@ -54,6 +55,10 @@ In short: See :ref:`below <pushing-to-main>`. +.. note:: It's usually a good idea to use the ``-n`` flag to ``git push`` + to check first that you're about to push the changes you want to + the place you want. + This way of working helps to keep work well organized and the history as clear as possible. @@ -74,16 +79,16 @@ as clear as possible. Making a new feature branch =========================== -:: +To update your master branch, use:: - git branch my-new-feature - git checkout my-new-feature + git fetch upstream + git merge upstream/master --ff-only -or just:: +To create a new branch and check it out, use:: git checkout -b my-new-feature upstream/master -Generally, you will want to keep this also on your public github_ fork +Generally, you will want to keep this branch also on your public github_ fork of NumPy_. To do this, you `git push`_ this new branch up to your github_ repo. Generally (if you followed the instructions in these pages, and by default), git will have a link to your github_ repo, called @@ -143,14 +148,53 @@ In more detail #. To commit all modified files into the local copy of your repo,, do ``git commit -am 'A commit message'``. Note the ``-am`` options to ``commit``. The ``m`` flag just signals that you're going to type a - message on the command line. The ``a`` flag - you can just take on - faith - or see `why the -a flag?`_ - and the helpful use-case description in - the `tangled working copy problem`_. The `git commit`_ manual - page might also be useful. + message on the command line. If you leave it out, an editor will open in + which you can compose your commit message. For non-trivial commits this is + often the better choice. The ``a`` flag - you can just take on faith - or + see `why the -a flag?`_ - and the helpful use-case description in the + `tangled working copy problem`_. The section on + :ref:`commit messages <writing-the-commit-message>` below might also be useful. #. To push the changes up to your forked repo on github_, do a ``git push`` (see `git push`). +.. _writing-the-commit-message: + +Writing the commit message +-------------------------- + +Commit messages should be clear and follow a few basic rules. Example:: + + ENH: add functionality X to numpy.<submodule>. + + The first line of the commit message starts with a capitalized acronym + (options listed below) indicating what type of commit this is. Then a blank + line, then more text if needed. Lines shouldn't be longer than 80 + characters. If the commit is related to a ticket, indicate that with + "See #3456", "See ticket 3456", "Closes #3456" or similar. + +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: fixed another one`` is an example of +what not to do; the reader has to go look for context elsewhere. + +Standard acronyms to start the commit message with are:: + + API: an (incompatible) API change + BLD: change related to building numpy + BUG: bug fix + DEP: deprecate something, or remove a deprecated object + DEV: development tool or utility + DOC: documentation + ENH: enhancement + MAINT: maintenance commit (refactoring, typos, etc.) + REV: revert an earlier commit + STY: style fix (whitespace, PEP8) + TST: addition or modification of tests + REL: related to releasing numpy + + .. _rebasing-on-master: Rebasing on master @@ -181,9 +225,9 @@ Then, the feature branch:: git rebase master If you have made changes to files that have changed also upstream, -this may generate merge conflicts that you need to resolve.:: +this may generate merge conflicts that you need to resolve. +Finally, remove the backup branch once the rebase succeeded:: - # delete backup branch git branch -D tmp .. _recovering-from-mess-up: @@ -216,6 +260,11 @@ If you forgot to make a backup branch:: # reset the branch to where it was before the botched rebase git reset --hard my-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 +http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts + .. _asking-for-merging: diff --git a/doc/source/dev/gitwash/following_latest.rst b/doc/source/dev/gitwash/following_latest.rst index 8e0b6e797..ad497bf9a 100644 --- a/doc/source/dev/gitwash/following_latest.rst +++ b/doc/source/dev/gitwash/following_latest.rst @@ -6,6 +6,8 @@ These are the instructions if you just want to follow the latest *NumPy* source, but you don't need to do any development for now. +If you do want to contribute a patch (excellent!) or do more extensive +NumPy development, see :ref:`development-workflow`. The steps are: diff --git a/doc/source/dev/gitwash/index.rst b/doc/source/dev/gitwash/index.rst index edbf4dbc3..f3038721e 100644 --- a/doc/source/dev/gitwash/index.rst +++ b/doc/source/dev/gitwash/index.rst @@ -10,7 +10,6 @@ Contents: git_intro following_latest - patching git_development git_resources diff --git a/doc/source/dev/gitwash/patching.rst b/doc/source/dev/gitwash/patching.rst deleted file mode 100644 index da8b660ac..000000000 --- a/doc/source/dev/gitwash/patching.rst +++ /dev/null @@ -1,132 +0,0 @@ -================ - Making a patch -================ - -You've discovered a bug or something else you want to change in -NumPy_ - excellent! - -You've worked out a way to fix it - even better! - -You want to tell us about it - best of all! - -The easiest way is to make a *patch* or set of patches. Here we explain -how. Making a patch is the simplest and quickest, but if you're going -to be doing anything more than simple quick things, please consider -following the :ref:`git-development` model instead. - -.. _making-patches: - -Making patches -============== - -Overview --------- - -:: - - # tell git who you are - git config --global user.email you@yourdomain.example.com - git config --global user.name "Your Name Comes Here" - # get the repository if you don't have it - git clone git://github.com/numpy/numpy.git - # make a branch for your patching - cd numpy - git branch the-fix-im-thinking-of - git checkout the-fix-im-thinking-of - # hack, hack, hack - # Tell git about any new files you've made - git add somewhere/tests/test_my_bug.py - # commit work in progress as you go - git commit -am 'BF - added tests for Funny bug' - # hack hack, hack - git commit -am 'BF - added fix for Funny bug' - # make the patch files - git format-patch -M -C master - -Then, create a ticket in the `Numpy Trac <http://projects.scipy.org/numpy/>`__, -attach the generated patch files there, and notify the `NumPy mailing list`_ -about your contribution. - -In detail ---------- - -#. Tell git_ who you are so it can label the commits you've made:: - - git config --global user.email you@yourdomain.example.com - git config --global user.name "Your Name Comes Here" - -#. If you don't already have one, clone a copy of the NumPy_ repository:: - - git clone git://github.com/numpy/numpy.git - cd numpy - -#. Make a 'feature branch'. This will be where you work on your bug - fix. It's nice and safe and leaves you with access to an unmodified - copy of the code in the main branch:: - - git branch the-fix-im-thinking-of - git checkout the-fix-im-thinking-of - -#. Do some edits, and commit them as you go:: - - # hack, hack, hack - # Tell git about any new files you've made - git add somewhere/tests/test_my_bug.py - # commit work in progress as you go - git commit -am 'BF - added tests for Funny bug' - # hack hack, hack - git commit -am 'BF - added fix for Funny bug' - - Note the ``-am`` options to ``commit``. The ``m`` flag just signals - that you're going to type a message on the command line. The ``a`` - flag - you can just take on faith - or see `why the -a flag?`_. - -#. When you have finished, check you have committed all your changes:: - - git status - -#. Finally, make your commits into patches. You want all the commits - since you branched from the ``master`` branch:: - - git format-patch -M -C master - - You will now have several files named for the commits:: - - 0001-BF-added-tests-for-Funny-bug.patch - 0002-BF-added-fix-for-Funny-bug.patch - - The recommended way to proceed is either to attach these files to - an enhancement ticket in the `Numpy Trac <http://projects.scipy.org/numpy/>`__ - and send a mail about the enhancement to the `NumPy mailing list`_. - - You can also consider sending your changes via Github, see below and in - :ref:`asking-for-merging`. - -When you are done, to switch back to the main copy of the code, just -return to the ``master`` branch:: - - git checkout master - -Moving from patching to development -=================================== - -If you find you have done some patches, and you have one or more feature -branches, you will probably want to switch to development mode. You can -do this with the repository you have. - -Fork the NumPy_ repository on github_ - :ref:`forking`. Then:: - - # checkout and refresh master branch from main repo - git checkout master - git fetch origin - git merge --ff-only origin/master - # rename pointer to main repository to 'upstream' - git remote rename origin upstream - # point your repo to default read / write to your fork on github - git remote add origin git@github.com:your-user-name/numpy.git - # push up any branches you've made and want to keep - git push origin the-fix-im-thinking-of - -Then you can, if you want, follow the :ref:`development-workflow`. - -.. include:: git_links.inc |