summaryrefslogtreecommitdiff
path: root/doc/source/dev/gitwash/development_workflow.rst
diff options
context:
space:
mode:
authorPauli Virtanen <pav@iki.fi>2010-10-04 21:32:16 +0200
committerPauli Virtanen <pav@iki.fi>2010-10-04 21:55:44 +0200
commit1f0c9286b83f4bd2cdcbeea02dc8846147823079 (patch)
treed5c05aeaaed21adc37beb7d42e1f34e4e7b5cd71 /doc/source/dev/gitwash/development_workflow.rst
parent8b0453630961b5788c83381c276c63273cdd53b7 (diff)
downloadnumpy-1f0c9286b83f4bd2cdcbeea02dc8846147823079.tar.gz
DOC: regenerate gitwash docs
Diffstat (limited to 'doc/source/dev/gitwash/development_workflow.rst')
-rw-r--r--doc/source/dev/gitwash/development_workflow.rst239
1 files changed, 239 insertions, 0 deletions
diff --git a/doc/source/dev/gitwash/development_workflow.rst b/doc/source/dev/gitwash/development_workflow.rst
new file mode 100644
index 000000000..2d9248054
--- /dev/null
+++ b/doc/source/dev/gitwash/development_workflow.rst
@@ -0,0 +1,239 @@
+.. _development-workflow:
+
+====================
+Development workflow
+====================
+
+You already have your own forked copy of the NumPy_ repository, by
+following :ref:`forking`, :ref:`set-up-fork`, and you have configured
+git_ by following :ref:`configure-git`.
+
+Workflow summary
+================
+
+* Keep your ``master`` branch clean of edits that have not been merged
+ to the main NumPy_ development repo. Your ``master`` then will follow
+ the main NumPy_ repository.
+* Start a new *feature branch* for each set of edits that you do.
+* If you can avoid it, try not to merge other branches into your feature
+ branch while you are working.
+* Ask for review!
+
+This way of working really helps to keep work well organized, and in
+keeping history as clear as possible.
+
+See - for example - `linux git workflow`_.
+
+Making a new feature branch
+===========================
+
+::
+
+ git branch my-new-feature
+ git checkout my-new-feature
+
+Generally, you will want to keep this 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
+``origin``. You push up to your own repo on github_ with::
+
+ git push origin my-new-feature
+
+In git >1.7 you can ensure that the link is correctly set by using the
+``--set-upstream`` option::
+
+ git push --set-upstream origin my-new-feature
+
+From now on git_ will know that ``my-new-feature`` is related to the
+``my-new-feature`` branch in the github_ repo.
+
+The editing workflow
+====================
+
+Overview
+--------
+
+::
+
+ # hack hack
+ git add my_new_file
+ git commit -am 'NF - some message'
+ git push
+
+In more detail
+--------------
+
+#. Make some changes
+#. See which files have changed with ``git status`` (see `git status`_).
+ You'll see a listing like this one::
+
+ # On branch ny-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)
+ #
+ # INSTALL
+ no changes added to commit (use "git add" and/or "git commit -a")
+
+#. Check what the actual changes are with ``git diff`` (`git diff`_).
+#. Add any new files to version control ``git add new_file_name`` (see
+ `git add`_).
+#. 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.
+#. To push the changes up to your forked repo on github_, do a ``git
+ push`` (see `git push`).
+
+Asking for code review
+======================
+
+#. Go to your repo URL - e.g. ``http://github.com/your-user-name/numpy``.
+#. Click on the *Branch list* button:
+
+ .. image:: branch_list.png
+
+#. Click on the *Compare* button for your feature branch - here ``my-new-feature``:
+
+ .. image:: branch_list_compare.png
+
+#. If asked, select the *base* and *comparison* branch names you want to
+ compare. Usually these will be ``master`` and ``my-new-feature``
+ (where that is your feature branch name).
+#. At this point you should get a nice summary of the changes. Copy the
+ URL for this, and post it to the `NumPy mailing list`_, asking for
+ review. The URL will look something like:
+ ``http://github.com/your-user-name/numpy/compare/master...my-new-feature``.
+ There's an example at
+ http://github.com/matthew-brett/nipy/compare/master...find-install-data
+ See: http://github.com/blog/612-introducing-github-compare-view for
+ more detail.
+
+The generated comparison, is between your feature branch
+``my-new-feature``, and the place in ``master`` from which you branched
+``my-new-feature``. In other words, you can keep updating ``master``
+without interfering with the output from the comparison. More detail?
+Note the three dots in the URL above (``master...my-new-feature``) and
+see :ref:`dot2-dot3`.
+
+Asking for your changes to be merged with the main repo
+=======================================================
+
+When you are ready to ask for the merge of your code:
+
+#. Go to the URL of your forked repo, say
+ ``http://github.com/your-user-name/numpy.git``.
+#. Click on the 'Pull request' button:
+
+ .. image:: pull_button.png
+
+ Enter a message; we suggest you select only ``NumPy`` as the
+ recipient. The message will go to the `NumPy mailing list`_. Please
+ feel free to add others from the list as you like.
+
+Merging from trunk
+==================
+
+This updates your code from the upstream `NumPy github`_ repo.
+
+Overview
+--------
+
+::
+
+ # go to your master branch
+ git checkout master
+ # pull changes from github
+ git fetch upstream
+ # merge from upstream
+ git merge upstream/master
+
+In detail
+---------
+
+We suggest that you do this only for your ``master`` branch, and leave
+your 'feature' branches unmerged, to keep their history as clean as
+possible. This makes code review easier::
+
+ git checkout master
+
+Make sure you have done :ref:`linking-to-upstream`.
+
+Merge the upstream code into your current development by first pulling
+the upstream repo to a copy on your local machine::
+
+ git fetch upstream
+
+then merging into your current branch::
+
+ git merge upstream/master
+
+Deleting a branch on github_
+============================
+
+::
+
+ git checkout master
+ # delete branch locally
+ git branch -D my-unwanted-branch
+ # delete branch on github
+ git push origin :my-unwanted-branch
+
+(Note the colon ``:`` before ``test-branch``. See also:
+http://github.com/guides/remove-a-remote-branch
+
+Several people sharing a single repository
+==========================================
+
+If you want to work on some stuff with other people, where you are all
+committing into the same repository, or even the same branch, then just
+share it via github_.
+
+First fork NumPy into your account, as from :ref:`forking`.
+
+Then, go to your forked repository github page, say
+``http://github.com/your-user-name/numpy``
+
+Click on the 'Admin' button, and add anyone else to the repo as a
+collaborator:
+
+ .. image:: pull_button.png
+
+Now all those people can do::
+
+ git clone git@githhub.com:your-user-name/numpy.git
+
+Remember that links starting with ``git@`` use the ssh protocol and are
+read-write; links starting with ``git://`` are read-only.
+
+Your collaborators can then commit directly into that repo with the
+usual::
+
+ git commit -am 'ENH - much better code'
+ git push origin master # pushes directly into your repo
+
+Exploring your repository
+=========================
+
+To see a graphical representation of the repository branches and
+commits::
+
+ gitk --all
+
+To see a linear list of commits for this branch::
+
+ git log
+
+You can also look at the `network graph visualizer`_ for your github_
+repo.
+
+.. include:: git_links.inc