development_workflow.rst
233 lines
| 6.9 KiB
| text/x-rst
|
RstLexer
|
r2599 | .. _development-workflow: | ||
==================== | ||||
Development workflow | ||||
==================== | ||||
You already have your own forked copy of the ipython_ 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 ipython_ development repo. Your ``master`` then will follow | ||||
the main ipython_ 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 ipython_. 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 | ||||
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?`_. See also the `git commit`_ manual | ||||
page. | ||||
#. 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/ipython``. | ||||
#. 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 `ipython mailing list`_, asking for | ||||
review. The URL will look something like: | ||||
``http://github.com/your-user-name/ipython/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/ipython.git``. | ||||
#. Click on the 'Pull request' button: | ||||
.. image:: pull_button.png | ||||
Enter a message; we suggest you select only ``ipython`` as the | ||||
recipient. The message will go to the `ipython mailing list`_. Please | ||||
feel free to add others from the list as you like. | ||||
Merging from trunk | ||||
================== | ||||
This updates your code from the upstream `ipython github`_ repo. | ||||
Overview | ||||
-------- | ||||
:: | ||||
# go to your master branch | ||||
git checkout master | ||||
# pull changes from github | ||||
git fetch upstream | ||||
# merge from upstream | ||||
|
r3295 | git merge upstream/master | ||
|
r2599 | |||
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 ipython into your account, as from :ref:`forking`. | ||||
Then, go to your forked repository github page, say | ||||
``http://github.com/your-user-name/ipython`` | ||||
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/ipython.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.txt | ||||