wassname/scikit-image
1
0
Fork 0
mirror of https://github.com/wassname/scikit-image.git synced 2026-07-03 01:09:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

DOC: Update gitwash generated docs.

Browse Source
This commit is contained in:
Stefan van der Walt
2011-07-15 17:09:37 -05:00
parent e57f7f0420
commit d025016b3c
20 changed files with 656 additions and 283 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/gitwash/branch_dropdown.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

doc/source/gitwash/branch_list.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

doc/source/gitwash/branch_list_compare.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

doc/source/gitwash/configure_git.txt
+122 -53
View File
@@ -9,81 +9,150 @@
Overview
========
::
Your personal git configurations are saved in the ``.gitconfig`` file in
your home directory.
git config --global user.email you@yourdomain.example.com
git config --global user.name "Your Name Comes Here"
Here is an example ``.gitconfig`` file::
In detail
=========
This is to tell git_ who you are, for labeling any changes you make to
the code. The simplest way to do this is from the command line::
git config --global user.email you@yourdomain.example.com
git config --global user.name "Your Name Comes Here"
This will write the settings into your git configuration file - a file
called ``.gitconfig`` in your home directory.
Advanced git configuration
==========================
You might well benefit from some aliases to common commands.
For example, you might well want to be able to shorten ``git checkout`` to ``git co``.
The easiest way to do this, is to create a ``.gitconfig`` file in your
home directory, with contents like this::
[core]
editor = emacs
[user]
name = Your Name
email = you@yourdomain.example.com
name = Your Name Comes Here
[alias]
ci = commit -a
co = checkout
st = status
stat = status
co = checkout
[color]
diff = auto
status = true
br = branch
wdiff = diff --color-words
(of course you'll need to set your email and name, and may want to set
your editor). If you prefer, you can do the same thing from the command
line::
[core]
editor = vim
git config --global core.editor emacs
[merge]
summary = true
You can edit this file directly or you can use the ``git config --global``
command::
git config --global user.name "Your Name"
git config --global user.email you@yourdomain.example.com
git config --global user.name "Your Name Comes Here"
git config --global alias.st status
git config --global alias.stat status
git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global color.diff auto
git config --global color.status true
These commands will write to your user's git configuration file
``~/.gitconfig``.
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"
git config --global core.editor vim
git config --global merge.summary true
To set up on another computer, you can copy your ``~/.gitconfig`` file,
or run the commands above.
Other configuration recommended by Yarik
========================================
In detail
=========
In your ``~/.gitconfig`` file alias section::
user.name and user.email
------------------------
wdiff = diff --color-words
It is good practice to tell git_ who you are, for labeling any changes
you make to the code. The simplest way to do this is from the command
line::
so that ``git wdiff`` gives a nicely formatted output of the diff.
git config --global user.name "Your Name"
git config --global user.email you@yourdomain.example.com
To enforce summaries when doing merges(``~/.gitconfig`` file again)::
This will write the settings into your git configuration file, which
should now contain a user section with your name and email::
[user]
name = Your Name
email = you@yourdomain.example.com
Of course you'll need to replace ``Your Name`` and ``you@yourdomain.example.com``
with your actual name and email address.
Aliases
-------
You might well benefit from some aliases to common commands.
For example, you might well want to be able to shorten ``git checkout``
to ``git co``. Or you may want to alias ``git diff --color-words``
(which gives a nicely formatted output of the diff) to ``git wdiff``
The following ``git config --global`` commands::
git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"
will create an ``alias`` section in your ``.gitconfig`` file with contents
like this::
[alias]
ci = commit -a
co = checkout
st = status -a
stat = status -a
br = branch
wdiff = diff --color-words
Editor
------
You may also want to make sure that your editor of choice is used ::
git config --global core.editor vim
Merging
-------
To enforce summaries when doing merges (``~/.gitconfig`` file again)::
[merge]
summary = true
log = true
Or from the command line::
.. include:: git_links.txt
git config --global merge.log true
.. _fancy-log:
Fancy log output
----------------
This is a very nice alias to get a fancy log output; it should go in the
``alias`` section of your ``.gitconfig`` file::
lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)[%an]%Creset' --abbrev-commit --date=relative
You use the alias with::
git lg
and it gives graph / text output something like this (but with color!)::
* 6d8e1ee - (HEAD, origin/my-fancy-feature, my-fancy-feature) NF - a fancy file (45 minutes ago) [Matthew Brett]
* d304a73 - (origin/placeholder, placeholder) Merge pull request #48 from hhuuggoo/master (2 weeks ago) [Jonathan Terhorst]
|\
| * 4aff2a8 - fixed bug 35, and added a test in test_bugfixes (2 weeks ago) [Hugo]
|/
* a7ff2e5 - Added notes on discussion/proposal made during Data Array Summit. (2 weeks ago) [Corran Webster]
* 68f6752 - Initial implimentation of AxisIndexer - uses 'index_by' which needs to be changed to a call on an Axes object - this is all very sketchy right now. (2 weeks ago) [Corr
* 376adbd - Merge pull request #46 from terhorst/master (2 weeks ago) [Jonathan Terhorst]
|\
| * b605216 - updated joshu example to current api (3 weeks ago) [Jonathan Terhorst]
| * 2e991e8 - add testing for outer ufunc (3 weeks ago) [Jonathan Terhorst]
| * 7beda5a - prevent axis from throwing an exception if testing equality with non-axis object (3 weeks ago) [Jonathan Terhorst]
| * 65af65e - convert unit testing code to assertions (3 weeks ago) [Jonathan Terhorst]
| * 956fbab - Merge remote-tracking branch 'upstream/master' (3 weeks ago) [Jonathan Terhorst]
| |\
| |/
Thanks to Yury V. Zaytsev for posting it.
.. include:: links.inc
doc/source/gitwash/development_workflow.txt
+294 -112
View File
@@ -1,47 +1,102 @@
.. _development-workflow:
====================
####################
Development workflow
====================
####################
You already have your own forked copy of the scikits.image_ repository, by
following :ref:`forking`, :ref:`set-up-fork`, and you have configured
git_ by following :ref:`configure-git`.
following :ref:`forking`. You have :ref:`set-up-fork`. You have configured
git by following :ref:`configure-git`. Now you are ready for some real work.
Workflow summary
================
* Keep your ``master`` branch clean of edits that have not been merged
to the main scikits.image_ development repo. Your ``master`` then will follow
the main scikits.image_ 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!
In what follows we'll refer to the upstream scikits.image ``master`` branch, as
"trunk".
This way of working really helps to keep work well organized, and in
keeping history as clear as possible.
* Don't use your ``master`` branch for anything. Consider deleting it.
* When you are starting a new set of changes, fetch any changes from trunk,
and start a new *feature branch* from that.
* Make a new branch for each separable set of changes |emdash| "one task, one
branch" (`ipython git workflow`_).
* Name your branch for the purpose of the changes - e.g.
``bugfix-for-issue-14`` or ``refactor-database-code``.
* If you can possibly avoid it, avoid merging trunk or any other branches into
your feature branch while you are working.
* If you do find yourself merging from trunk, consider :ref:`rebase-on-trunk`
* Ask on the `scikits.image mailing list`_ if you get stuck.
* Ask for code review!
See - for example - `linux git workflow`_.
This way of working helps to keep work well organized, with readable history.
This in turn makes it easier for project maintainers (that might be you) to see
what you've done, and why you did it.
Making a new feature branch
===========================
See `linux git workflow`_ and `ipython git workflow`_ for some explanation.
Consider deleting your master branch
====================================
It may sound strange, but deleting your own ``master`` branch can help reduce
confusion about which branch you are on. See `deleting master on github`_ for
details.
.. _update-mirror-trunk:
Update the mirror of trunk
==========================
First make sure you have done :ref:`linking-to-upstream`.
From time to time you should fetch the upstream (trunk) changes from github::
git fetch upstream
This will pull down any commits you don't have, and set the remote branches to
point to the right commit. For example, 'trunk' is the branch referred to by
(remote/branchname) ``upstream/master`` - and if there have been commits since
you last checked, ``upstream/master`` will change after you do the fetch.
.. _make-feature-branch:
Make a new feature branch
=========================
When you are ready to make some changes to the code, you should start a new
branch. Branches that are for a collection of related edits are often called
'feature branches'.
Making an new branch for each set of related changes will make it easier for
someone reviewing your branch to see what you are doing.
Choose an informative name for the branch to remind yourself and the rest of us
what the changes in the branch are for. For example ``add-ability-to-fly``, or
``buxfix-for-issue-42``.
::
git branch my-new-feature
git checkout my-new-feature
# Update the mirror of trunk
git fetch upstream
# Make new feature branch starting at current trunk
git branch my-new-feature upstream/master
git checkout my-new-feature
Generally, you will want to keep this also on your public github_ fork
of scikits.image_. 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::
Generally, you will want to keep your feature branches on your public github_
fork of scikits.image_. 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.
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.
.. _edit-flow:
The editing workflow
====================
@@ -78,101 +133,46 @@ In more detail
#. 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`_).
`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`).
message on the command line. The ``a`` flag |emdash| you can just take on
faith |emdash| or see `why the -a flag?`_ |emdash| 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
======================
Ask for your changes to be reviewed or merged
=============================================
#. Go to your repo URL - e.g. ``http://github.com/your-user-name/scikits.image``.
#. 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 `scikits.image mailing list`_, asking for
review. The URL will look something like:
``http://github.com/your-user-name/scikits.image/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:
When you are ready to ask for someone to review your code and consider a merge:
#. Go to the URL of your forked repo, say
``http://github.com/your-user-name/scikits.image.git``.
``http://github.com/your-user-name/scikits.image``.
#. Use the 'Switch Branches' dropdown menu near the top left of the page to
select the branch with your changes:
.. image:: branch_dropdown.png
#. Click on the 'Pull request' button:
.. image:: pull_button.png
Enter a message; we suggest you select only ``scikits.image`` as the
recipient. The message will go to the `scikits.image mailing list`_. Please
feel free to add others from the list as you like.
Enter a title for the set of changes, and some explanation of what you've
done. Say if there is anything you'd like particular attention for - like a
complicated change or some code you are not happy with.
Merging from trunk
==================
If you don't think your request is ready to be merged, just say so in your
pull request message. This is still a good way of getting some preliminary
code review.
This updates your code from the upstream `scikits.image github`_ repo.
Some other things you might want to do
======================================
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_
============================
Delete a branch on github
-------------------------
::
@@ -186,11 +186,11 @@ Deleting a branch on github_
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_.
share it via github.
First fork scikits.image into your account, as from :ref:`forking`.
@@ -215,8 +215,8 @@ usual::
git commit -am 'ENH - much better code'
git push origin master # pushes directly into your repo
Exploring your repository
=========================
Explore your repository
-----------------------
To see a graphical representation of the repository branches and
commits::
@@ -227,7 +227,189 @@ To see a linear list of commits for this branch::
git log
You can also look at the `network graph visualizer`_ for your github_
You can also look at the `network graph visualizer`_ for your github
repo.
.. include:: git_links.txt
Finally the :ref:`fancy-log` ``lg`` alias will give you a reasonable text-based
graph of the repository.
.. _rebase-on-trunk:
Rebasing on trunk
-----------------
Let's say you thought of some work you'd like to do. You
:ref:`update-mirror-trunk` and :ref:`make-feature-branch` called
``cool-feature``. At this stage trunk is at some commit, let's call it E. Now
you make some new commits on your ``cool-feature`` branch, let's call them A, B,
C. Maybe your changes take a while, or you come back to them after a while. In
the meantime, trunk has progressed from commit E to commit (say) G::
A---B---C cool-feature
/
D---E---F---G trunk
At this stage you consider merging trunk into your feature branch, and you
remember that this here page sternly advises you not to do that, because the
history will get messy. Most of the time you can just ask for a review, and not
worry that trunk has got a little ahead. But sometimes, the changes in trunk
might affect your changes, and you need to harmonize them. In this situation
you may prefer to do a rebase.
rebase takes your changes (A, B, C) and replays them as if they had been made to
the current state of ``trunk``. In other words, in this case, it takes the
changes represented by A, B, C and replays them on top of G. After the rebase,
your history will look like this::
A'--B'--C' cool-feature
/
D---E---F---G trunk
See `rebase without tears`_ for more detail.
To do a rebase on trunk::
# Update the mirror of trunk
git fetch upstream
# go to the feature branch
git checkout cool-feature
# make a backup in case you mess up
git branch tmp cool-feature
# rebase cool-feature onto trunk
git rebase --onto upstream/master upstream/master cool-feature
In this situation, where you are already on branch ``cool-feature``, the last
command can be written more succinctly as::
git rebase upstream/master
When all looks good you can delete your backup branch::
git branch -D tmp
If it doesn't look good you may need to have a look at
:ref:`recovering-from-mess-up`.
If you have made changes to files that have also changed in trunk, this may
generate merge conflicts that you need to resolve - see the `git rebase`_ man
page for some instructions at the end of the "Description" section. There is
some related help on merging in the git user manual - see `resolving a merge`_.
.. _recovering-from-mess-up:
Recovering from mess-ups
------------------------
Sometimes, you mess up merges or rebases. Luckily, in git it is
relatively straightforward to recover from such mistakes.
If you mess up during a rebase::
git rebase --abort
If you notice you messed up after the rebase::
# reset branch back to the saved point
git reset --hard tmp
If you forgot to make a backup branch::
# look at the reflog of the branch
git reflog show cool-feature
8630830 cool-feature@{0}: commit: BUG: io: close file handles immediately
278dd2a cool-feature@{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d
26aa21a cool-feature@{2}: commit: BUG: lib: make seek_gzip_factory not leak gzip obj
...
# reset the branch to where it was before the botched rebase
git reset --hard cool-feature@{2}
.. _rewriting-commit-history:
Rewriting commit history
------------------------
.. note::
Do this only for your own feature branches.
There's an embarassing typo in a commit you made? Or perhaps the you
made several false starts you would like the posterity not to see.
This can be done via *interactive rebasing*.
Suppose that the commit history looks like this::
git log --oneline
eadc391 Fix some remaining bugs
a815645 Modify it so that it works
2dec1ac Fix a few bugs + disable
13d7934 First implementation
6ad92e5 * masked is now an instance of a new object, MaskedConstant
29001ed Add pre-nep for a copule of structured_array_extensions.
...
and ``6ad92e5`` is the last commit in the ``cool-feature`` branch. Suppose we
want to make the following changes:
* Rewrite the commit message for ``13d7934`` to something more sensible.
* Combine the commits ``2dec1ac``, ``a815645``, ``eadc391`` into a single one.
We do as follows::
# make a backup of the current state
git branch tmp HEAD
# interactive rebase
git rebase -i 6ad92e5
This will open an editor with the following text in it::
pick 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
pick a815645 Modify it so that it works
pick eadc391 Fix some remaining bugs
# 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::
r 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
f a815645 Modify it so that it works
f eadc391 Fix some remaining bugs
This means that (i) we want to edit the commit message for
``13d7934``, and (ii) collapse the last three commits into one. Now we
save and quit the editor.
Git will then immediately bring up an editor for editing the commit
message. After revising it, we get the output::
[detached HEAD 721fc64] FOO: First implementation
2 files changed, 199 insertions(+), 66 deletions(-)
[detached HEAD 0f22701] Fix a few bugs + disable
1 files changed, 79 insertions(+), 61 deletions(-)
Successfully rebased and updated refs/heads/my-feature-branch.
and the history looks now like this::
0f22701 Fix a few bugs + disable
721fc64 ENH: Sophisticated feature
6ad92e5 * masked is now an instance of a new object, MaskedConstant
If it went wrong, recovery is again possible as explained :ref:`above
<recovering-from-mess-up>`.
.. include:: links.inc
doc/source/gitwash/dot2_dot3.txt
-28
View File
@@ -1,28 +0,0 @@
.. _dot2-dot3:
========================================
Two and three dots in difference specs
========================================
Thanks to Yarik Halchenko for this explanation.
Imagine a series of commits A, B, C, D... Imagine that there are two
branches, *topic* and *master*. You branched *topic* off *master* when
*master* was at commit 'E'. The graph of the commits looks like this::
A---B---C topic
/
D---E---F---G master
Then::
git diff master..topic
will output the difference from G to C (i.e. with effects of F and G),
while::
git diff master...topic
would output just differences in the topic branch (i.e. only A, B, and
C).
doc/source/gitwash/following_latest.txt
+2 -2
View File
@@ -10,7 +10,7 @@ These are the instructions if you just want to follow the latest
The steps are:
* :ref:`install-git`
* get local copy of the git repository from github_
* get local copy of the git repository from github
* update local copy from time to time
Get the local copy of the code
@@ -33,4 +33,4 @@ From time to time you may want to pull down the latest code. Do this with::
The tree in ``scikits.image`` will now have the latest changes from the initial
repository.
.. include:: git_links.txt
.. include:: links.inc
doc/source/gitwash/forking_hell.txt
+12 -12
View File
@@ -1,26 +1,26 @@
.. _forking:
============================================
==========================================
Making your own copy (fork) of scikits.image
============================================
==========================================
You need to do this only once. The instructions here are very similar
to the instructions at http://help.github.com/forking/ - please see that
page for more detail. We're repeating some of it here just to give the
to the instructions at http://help.github.com/forking/ |emdash| please see
that page for more detail. We're repeating some of it here just to give the
specifics for the scikits.image_ project, and to suggest some default names.
Set up and configure a github_ account
======================================
Set up and configure a github account
=====================================
If you don't have a github_ account, go to the github_ page, and make one.
If you don't have a github account, go to the github page, and make one.
You then need to configure your account to allow write access - see the
``Generating SSH keys`` help on `github help`_.
You then need to configure your account to allow write access |emdash| see
the ``Generating SSH keys`` help on `github help`_.
Create your own forked copy of scikits.image_
=============================================
===========================================
#. Log into your github_ account.
#. Log into your github account.
#. Go to the scikits.image_ github home at `scikits.image github`_.
#. Click on the *fork* button:
@@ -29,5 +29,5 @@ Create your own forked copy of scikits.image_
Now, after a short pause and some 'Hardcore forking action', you
should find yourself at the home page for your own forked copy of scikits.image_.
.. include:: git_links.txt
.. include:: links.inc
doc/source/gitwash/git_development.txt
+1 -1
View File
@@ -13,4 +13,4 @@ Contents:
set_up_fork
configure_git
development_workflow
maintainer_workflow
doc/source/gitwash/git_install.txt
+3 -3
View File
@@ -17,10 +17,10 @@ OS X Use the git-osx-installer_
In detail
=========
See the git_ page for the most recent information.
See the git page for the most recent information.
Have a look at the github_ install help pages available from `github help`_
Have a look at the github install help pages available from `github help`_
There are good instructions here: http://book.git-scm.com/2_installing_git.html
.. include:: git_links.txt
.. include:: links.inc
doc/source/gitwash/git_intro.txt
+5 -5
View File
@@ -8,11 +8,11 @@ project.
There are several different workflows here, for different ways of
working with *scikits.image*.
This is not a comprehensive git_ reference, it's just a workflow for our
own project. It's tailored to the github_ hosting service. You may well
find better or quicker ways of getting stuff done with git_, but these
This is not a comprehensive git reference, it's just a workflow for our
own project. It's tailored to the github hosting service. You may well
find better or quicker ways of getting stuff done with git, but these
should get you started.
For general resources for learning git_ see :ref:`git-resources`.
For general resources for learning git, see :ref:`git-resources`.
.. include:: git_links.txt
.. include:: links.inc
doc/source/gitwash/git_links.txt → doc/source/gitwash/git_links.inc
+15 -24
View File
@@ -2,35 +2,12 @@
and name substitutions. It may be included in many files,
therefore it should only contain link targets and name
substitutions. Try grepping for "^\.\. _" to find plausible
candidates for this list.
candidates for this list.
.. NOTE: reST targets are
__not_case_sensitive__, so only one target definition is needed for
nipy, NIPY, Nipy, etc...
.. scikits.image
.. _`scikits.image`: http://stefanv.github.com/scikits.image
.. _`scikits.image github`: http://github.com/stefanv/scikits.image
.. _`scikits.image mailing list`: http://groups.google.com/group/scikits-image
.. PROJECTNAME placeholders
.. _PROJECTNAME: http://neuroimaging.scipy.org
.. _`PROJECTNAME github`: http://github.com/nipy
.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
.. nipy
.. _nipy: http://neuroimaging.scipy.org
.. _`nipy github`: http://github.com/nipy
.. _`nipy mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
.. ipython
.. _ipython: http://ipython.scipy.org
.. _`ipython github`: http://github.com/ipython
.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
.. git stuff
.. _git: http://git-scm.com/
.. _github: http://github.com
@@ -62,9 +39,23 @@
.. _git log: http://www.kernel.org/pub/software/scm/git/docs/git-log.html
.. _git branch: http://www.kernel.org/pub/software/scm/git/docs/git-branch.html
.. _git remote: http://www.kernel.org/pub/software/scm/git/docs/git-remote.html
.. _git rebase: http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html
.. _git config: http://www.kernel.org/pub/software/scm/git/docs/git-config.html
.. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
.. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
.. _tangled working copy problem: http://tomayko.com/writings/the-thing-about-git
.. _git management: http://kerneltrap.org/Linux/Git_Management
.. _linux git workflow: http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html
.. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html
.. _git foundation: http://matthew-brett.github.com/pydagogue/foundation.html
.. _deleting master on github: http://matthew-brett.github.com/pydagogue/gh_delete_master.html
.. _rebase without tears: http://matthew-brett.github.com/pydagogue/rebase_without_tears.html
.. _resolving a merge: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#resolving-a-merge
.. _ipython git workflow: http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html
.. other stuff
.. _python: http://www.python.org
.. |emdash| unicode:: U+02014
.. vim: ft=rst
doc/source/gitwash/git_resources.txt
+13 -11
View File
@@ -1,8 +1,8 @@
.. _git-resources:
================
git_ resources
================
=============
git resources
=============
Tutorials and summaries
=======================
@@ -14,18 +14,20 @@ Tutorials and summaries
* The `git user manual`_
* The `git tutorial`_
* The `git community book`_
* `git ready`_ - a nice series of tutorials
* `git casts`_ - video snippets giving git how-tos.
* `git magic`_ - extended introduction with intermediate detail
* Fernando Perez' git page - `Fernando's git page`_ - many links and tips
* `git ready`_ |emdash| a nice series of tutorials
* `git casts`_ |emdash| video snippets giving git how-tos.
* `git magic`_ |emdash| extended introduction with intermediate detail
* The `git parable`_ is an easy read explaining the concepts behind git.
* `git foundation`_ expands on the `git parable`_.
* Fernando Perez' git page |emdash| `Fernando's git page`_ |emdash| many
links and tips
* A good but technical page on `git concepts`_
* Th `git parable`_ is an easy read explaining the concepts behind git.
* `git svn crash course`_: git_ for those of us used to subversion_
* `git svn crash course`_: git for those of us used to subversion_
Advanced git workflow
=====================
There are many ways of working with git_; here are some posts on the
There are many ways of working with git; here are some posts on the
rules of thumb that other projects have come up with:
* Linus Torvalds on `git management`_
@@ -54,4 +56,4 @@ online manual pages for some common commands:
* `git remote`_
* `git status`_
.. include:: git_links.txt
.. include:: links.inc
doc/source/gitwash/index.txt
+1 -1
View File
@@ -1,7 +1,7 @@
.. _using-git:
Working with *scikits.image* source code
========================================
======================================
Contents:
doc/source/gitwash/known_projects.inc
+41
View File
@@ -0,0 +1,41 @@
.. Known projects
.. PROJECTNAME placeholders
.. _PROJECTNAME: http://neuroimaging.scipy.org
.. _`PROJECTNAME github`: http://github.com/nipy
.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
.. numpy
.. _numpy: hhttp://numpy.scipy.org
.. _`numpy github`: http://github.com/numpy/numpy
.. _`numpy mailing list`: http://mail.scipy.org/mailman/listinfo/numpy-discussion
.. scipy
.. _scipy: http://www.scipy.org
.. _`scipy github`: http://github.com/scipy/scipy
.. _`scipy mailing list`: http://mail.scipy.org/mailman/listinfo/scipy-dev
.. nipy
.. _nipy: http://nipy.org/nipy
.. _`nipy github`: http://github.com/nipy/nipy
.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
.. ipython
.. _ipython: http://ipython.scipy.org
.. _`ipython github`: http://github.com/ipython/ipython
.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
.. dipy
.. _dipy: http://nipy.org/dipy
.. _`dipy github`: http://github.com/Garyfallidis/dipy
.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
.. nibabel
.. _nibabel: http://nipy.org/nibabel
.. _`nibabel github`: http://github.com/nipy/nibabel
.. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
.. marsbar
.. _marsbar: http://marsbar.sourceforge.net
.. _`marsbar github`: http://github.com/matthew-brett/marsbar
.. _`MarsBaR mailing list`: https://lists.sourceforge.net/lists/listinfo/marsbar-users
doc/source/gitwash/links.inc
+4
View File
@@ -0,0 +1,4 @@
.. compiling links file
.. include:: known_projects.inc
.. include:: this_project.inc
.. include:: git_links.inc
doc/source/gitwash/maintainer_workflow.txt
+96
View File
@@ -0,0 +1,96 @@
.. _maintainer-workflow:
###################
Maintainer workflow
###################
This page is for maintainers |emdash| those of us who merge our own or other
peoples' changes into the upstream repository.
Being as how you're a maintainer, you are completely on top of the basic stuff
in :ref:`development-workflow`.
The instructions in :ref:`linking-to-upstream` add a remote that has read-only
access to the upstream repo. Being a maintainer, you've got read-write access.
It's good to have your upstream remote have a scary name, to remind you that
it's a read-write remote::
git remote add upstream-rw git@github.com:scikits.image/scikits.image.git
git fetch upstream-rw
*******************
Integrating changes
*******************
Let's say you have some changes that need to go into trunk
(``upstream-rw/master``).
The changes are in some branch that you are currently on. For example, you are
looking at someone's changes like this::
git remote add someone git://github.com/someone/scikits.image.git
git fetch someone
git branch cool-feature --track someone/cool-feature
git checkout cool-feature
So now you are on the branch with the changes to be incorporated upstream. The
rest of this section assumes you are on this branch.
A few commits
=============
If there are only a few commits, consider rebasing to upstream::
# Fetch upstream changes
git fetch upstream-rw
# rebase
git rebase upstream-rw/master
Remember that, if you do a rebase, and push that, you'll have to close any
github pull requests manually, because github will not be able to detect the
changes have already been merged.
A long series of commits
========================
If there are a longer series of related commits, consider a merge instead::
git fetch upstream-rw
git merge --no-ff upstream-rw/master
The merge will be detected by github, and should close any related pull requests
automatically.
Note the ``--no-ff`` above. This forces git to make a merge commit, rather than
doing a fast-forward, so that these set of commits branch off trunk then rejoin
the main history with a merge, rather than appearing to have been made directly
on top of trunk.
Check the history
=================
Now, in either case, you should check that the history is sensible and you have
the right commits::
git log --oneline --graph
git log -p upstream-rw/master..
The first line above just shows the history in a compact way, with a text
representation of the history graph. The second line shows the log of commits
excluding those that can be reached from trunk (``upstream-rw/master``), and
including those that can be reached from current HEAD (implied with the ``..``
at the end). So, it shows the commits unique to this branch compared to trunk.
The ``-p`` option shows the diff for these commits in patch form.
Push to trunk
=============
::
git push upstream-rw my-new-feature:master
This pushes the ``my-new-feature`` branch in this repository to the ``master``
branch in the ``upstream-rw`` repository.
.. include:: links.inc
doc/source/gitwash/patching.txt
+38 -27
View File
@@ -2,16 +2,18 @@
Making a patch
================
You've discovered a bug or something else you want to change in scikits.image_ - excellent!
You've discovered a bug or something else you want to change
in scikits.image_ .. |emdash| excellent!
You've worked out a way to fix it - even better!
You've worked out a way to fix it |emdash| even better!
You want to tell us about it - best of all!
You want to tell us about it |emdash| 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.
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:
@@ -42,24 +44,28 @@ Overview
# make the patch files
git format-patch -M -C master
Then, send the generated patch files to the `scikits.image mailing list`_ - where we will thank you warmly.
Then, send the generated patch files to the `scikits.image
mailing list`_ |emdash| where we will thank you warmly.
In detail
---------
#. Tell git_ who you are so it can label the commits you've made::
#. 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 scikits.image_ repository::
#. If you don't already have one, clone a copy of the
scikits.image_ repository::
git clone git://github.com/scikits.image/scikits.image.git
cd scikits.image
#. 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::
#. 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
@@ -74,16 +80,18 @@ In detail
# 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?`_.
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 |emdash| you can just take on faith |emdash|
or see `why the -a flag?`_.
#. When you have finished, check you have committed all your changes::
#. 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::
#. Finally, make your commits into patches. You want all the
commits since you branched from the ``master`` branch::
git format-patch -M -C master
@@ -94,19 +102,21 @@ In detail
Send these files to the `scikits.image mailing list`_.
When you are done, to switch back to the main copy of the code, just
return to the ``master`` branch::
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.
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 scikits.image_ repository on github_ - :ref:`forking`. Then::
Fork the scikits.image_ repository on github |emdash| :ref:`forking`.
Then::
# checkout and refresh master branch from main repo
git checkout master
@@ -118,6 +128,7 @@ Fork the scikits.image_ repository on github_ - :ref:`forking`. Then::
# 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`.
Then you can, if you want, follow the
:ref:`development-workflow`.
.. include:: git_links.txt
.. include:: links.inc
doc/source/gitwash/set_up_fork.txt
+4 -4
View File
@@ -4,14 +4,14 @@
Set up your fork
==================
First you follow the instructions for :ref:`forking`.
First you follow the instructions for :ref:`forking`.
Overview
========
::
git clone git@github.com/your-user-name/scikits.image.git
git clone git@github.com:your-user-name/scikits.image.git
cd scikits.image
git remote add upstream git://github.com/scikits.image/scikits.image.git
@@ -33,7 +33,7 @@ Clone your fork
This tells you that you are currently on the ``master`` branch, and
that you also have a ``remote`` connection to ``origin/master``.
What remote repository is ``remote/origin``? Try ``git remote -v`` to
see the URLs for the remote. They will point to your github_ fork.
see the URLs for the remote. They will point to your github fork.
Now you want to connect to the upstream `scikits.image github`_ repository, so
you can merge in changes from trunk.
@@ -64,5 +64,5 @@ Just for your own satisfaction, show yourself that you now have a new
origin git@github.com:your-user-name/scikits.image.git (fetch)
origin git@github.com:your-user-name/scikits.image.git (push)
.. include:: git_links.txt
.. include:: links.inc
doc/source/gitwash/this_project.inc
+5
View File
@@ -0,0 +1,5 @@
.. scikits.image
.. _scikits.image: http://scikits-image.org
.. _`scikits.image github`: http://github.com/scikits.image/scikits.image
.. _`scikits.image mailing list`: http://groups.google.com/group/scikits-image