Browse files

Merge pull request #455 from rgommers/devguide-update

Devguide update
  • Loading branch information...
2 parents 43f1d5c + c906fdc commit 0022325e516fd249bd1b754b9363f2b8b793d148 @charris charris committed Oct 3, 2012
View
4 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
###############
View
73 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:
View
2 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:
View
1 doc/source/dev/gitwash/index.rst
@@ -10,7 +10,6 @@ Contents:
git_intro
following_latest
- patching
git_development
git_resources
View
132 doc/source/dev/gitwash/patching.rst
@@ -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

0 comments on commit 0022325

Please sign in to comment.