[med-svn] [python-mne] 233/376: DOC : adding gitwash to the doc
Yaroslav Halchenko
debian at onerussian.com
Fri Nov 27 17:22:53 UTC 2015
This is an automated email from the git hooks/post-receive script.
yoh pushed a commit to annotated tag v0.1
in repository python-mne.
commit a5fab20f6efb63b5e82baa8befb112ec72e2c128
Author: Alexandre Gramfort <alexandre.gramfort at inria.fr>
Date: Thu May 5 11:13:47 2011 -0400
DOC : adding gitwash to the doc
---
doc/source/gitwash/branch_list.png | Bin 0 -> 13361 bytes
doc/source/gitwash/branch_list_compare.png | Bin 0 -> 10679 bytes
doc/source/gitwash/configure_git.rst | 123 +++++++++++++
doc/source/gitwash/development_workflow.rst | 265 ++++++++++++++++++++++++++++
doc/source/gitwash/following_latest.rst | 36 ++++
doc/source/gitwash/forking_button.png | Bin 0 -> 13092 bytes
doc/source/gitwash/forking_hell.rst | 33 ++++
doc/source/gitwash/git_development.rst | 16 ++
doc/source/gitwash/git_install.rst | 26 +++
doc/source/gitwash/git_intro.rst | 18 ++
doc/source/gitwash/git_links.inc | 54 ++++++
doc/source/gitwash/git_resources.rst | 59 +++++++
doc/source/gitwash/index.rst | 18 ++
doc/source/gitwash/known_projects.inc | 41 +++++
doc/source/gitwash/links.inc | 4 +
doc/source/gitwash/patching.rst | 134 ++++++++++++++
doc/source/gitwash/pull_button.png | Bin 0 -> 12893 bytes
doc/source/gitwash/set_up_fork.rst | 68 +++++++
doc/source/gitwash/setup.sh | 3 +
doc/source/gitwash/this_project.inc | 5 +
doc/source/index.rst | 13 ++
21 files changed, 916 insertions(+)
diff --git a/doc/source/gitwash/branch_list.png b/doc/source/gitwash/branch_list.png
new file mode 100644
index 0000000..1196eb7
Binary files /dev/null and b/doc/source/gitwash/branch_list.png differ
diff --git a/doc/source/gitwash/branch_list_compare.png b/doc/source/gitwash/branch_list_compare.png
new file mode 100644
index 0000000..336afa3
Binary files /dev/null and b/doc/source/gitwash/branch_list_compare.png differ
diff --git a/doc/source/gitwash/configure_git.rst b/doc/source/gitwash/configure_git.rst
new file mode 100644
index 0000000..e1dde37
--- /dev/null
+++ b/doc/source/gitwash/configure_git.rst
@@ -0,0 +1,123 @@
+.. _configure-git:
+
+===============
+ Configure git
+===============
+
+.. _git-config-basic:
+
+Overview
+========
+
+Your personal git_ configurations are saved in the ``.gitconfig`` file in
+your home directory.
+Here is an example ``.gitconfig`` file::
+
+ [user]
+ name = Your Name
+ email = you at yourdomain.example.com
+
+ [alias]
+ ci = commit -a
+ co = checkout
+ st = status
+ stat = status
+ br = branch
+ wdiff = diff --color-words
+
+ [core]
+ editor = vim
+
+ [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 at yourdomain.example.com
+ 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"
+ 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.
+
+In detail
+=========
+
+user.name and user.email
+------------------------
+
+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::
+
+ git config --global user.name "Your Name"
+ git config --global user.email you at yourdomain.example.com
+
+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 at yourdomain.example.com
+
+Of course you'll need to replace ``Your Name`` and ``you at 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]
+ log = true
+
+Or from the command line::
+
+ git config --global merge.log true
+
+
+.. include:: links.inc
diff --git a/doc/source/gitwash/development_workflow.rst b/doc/source/gitwash/development_workflow.rst
new file mode 100644
index 0000000..5056f15
--- /dev/null
+++ b/doc/source/gitwash/development_workflow.rst
@@ -0,0 +1,265 @@
+.. _development-workflow:
+
+====================
+Development workflow
+====================
+
+You already have your own forked copy of the mne-python_ 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 mne-python_ development repo. Your ``master`` then will follow
+ the main mne-python_ 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 |emdash| for example |emdash| `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 mne-python_. 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 |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
+======================
+
+#. Go to your repo URL |emdash| e.g. ``http://github.com/your-user-name/mne-python``.
+#. Click on the *Branch list* button:
+
+ .. image:: branch_list.png
+
+#. Click on the *Compare* button for your feature branch |emdash| 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 `mne-python mailing list`_, asking for
+ review. The URL will look something like:
+ ``http://github.com/your-user-name/mne-python/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``).
+
+.. admonition:: Two vs three dots
+
+ 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). [#thank_yarik]_
+
+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/mne-python.git``.
+#. Click on the 'Pull request' button:
+
+ .. image:: pull_button.png
+
+ Enter a message; we suggest you select only ``mne-python`` as the
+ recipient. The message will go to the `mne-python mailing list`_. Please
+ feel free to add others from the list as you like.
+
+Merging from trunk
+==================
+
+This updates your code from the upstream `mne-python 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 mne-python into your account, as from :ref:`forking`.
+
+Then, go to your forked repository github page, say
+``http://github.com/your-user-name/mne-python``
+
+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 at githhub.com:your-user-name/mne-python.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:: links.inc
+
+.. rubric:: Footnotes
+
+.. [#thank_yarik] Thanks to Yarik Halchenko for this explanation.
diff --git a/doc/source/gitwash/following_latest.rst b/doc/source/gitwash/following_latest.rst
new file mode 100644
index 0000000..4679c41
--- /dev/null
+++ b/doc/source/gitwash/following_latest.rst
@@ -0,0 +1,36 @@
+.. _following-latest:
+
+=============================
+ Following the latest source
+=============================
+
+These are the instructions if you just want to follow the latest
+*mne-python* source, but you don't need to do any development for now.
+
+The steps are:
+
+* :ref:`install-git`
+* get local copy of the git repository from github_
+* update local copy from time to time
+
+Get the local copy of the code
+==============================
+
+From the command line::
+
+ git clone git://github.com/mne-tools/mne-python.git
+
+You now have a copy of the code tree in the new ``mne-python`` directory.
+
+Updating the code
+=================
+
+From time to time you may want to pull down the latest code. Do this with::
+
+ cd mne-python
+ git pull
+
+The tree in ``mne-python`` will now have the latest changes from the initial
+repository.
+
+.. include:: links.inc
diff --git a/doc/source/gitwash/forking_button.png b/doc/source/gitwash/forking_button.png
new file mode 100644
index 0000000..d0e0413
Binary files /dev/null and b/doc/source/gitwash/forking_button.png differ
diff --git a/doc/source/gitwash/forking_hell.rst b/doc/source/gitwash/forking_hell.rst
new file mode 100644
index 0000000..bec4860
--- /dev/null
+++ b/doc/source/gitwash/forking_hell.rst
@@ -0,0 +1,33 @@
+.. _forking:
+
+==========================================
+Making your own copy (fork) of mne-python
+==========================================
+
+You need to do this only once. The instructions here are very similar
+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 mne-python_ project, and to suggest some default names.
+
+Set up and configure a github_ account
+======================================
+
+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 |emdash| see
+the ``Generating SSH keys`` help on `github help`_.
+
+Create your own forked copy of mne-python_
+===========================================
+
+#. Log into your github_ account.
+#. Go to the mne-python_ github home at `mne-python github`_.
+#. Click on the *fork* button:
+
+ .. image:: forking_button.png
+
+ Now, after a short pause and some 'Hardcore forking action', you
+ should find yourself at the home page for your own forked copy of mne-python_.
+
+.. include:: links.inc
+
diff --git a/doc/source/gitwash/git_development.rst b/doc/source/gitwash/git_development.rst
new file mode 100644
index 0000000..64522c6
--- /dev/null
+++ b/doc/source/gitwash/git_development.rst
@@ -0,0 +1,16 @@
+.. _git-development:
+
+=====================
+ Git for development
+=====================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ forking_hell
+ set_up_fork
+ configure_git
+ development_workflow
+
diff --git a/doc/source/gitwash/git_install.rst b/doc/source/gitwash/git_install.rst
new file mode 100644
index 0000000..a87224d
--- /dev/null
+++ b/doc/source/gitwash/git_install.rst
@@ -0,0 +1,26 @@
+.. _install-git:
+
+=============
+ Install git
+=============
+
+Overview
+========
+
+================ =============
+Debian / Ubuntu ``sudo apt-get install git-core``
+Fedora ``sudo yum install git-core``
+Windows Download and install msysGit_
+OS X Use the git-osx-installer_
+================ =============
+
+In detail
+=========
+
+See the git_ page for the most recent information.
+
+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:: links.inc
diff --git a/doc/source/gitwash/git_intro.rst b/doc/source/gitwash/git_intro.rst
new file mode 100644
index 0000000..755ee33
--- /dev/null
+++ b/doc/source/gitwash/git_intro.rst
@@ -0,0 +1,18 @@
+==============
+ Introduction
+==============
+
+These pages describe a git_ and github_ workflow for the mne-python_
+project.
+
+There are several different workflows here, for different ways of
+working with *mne-python*.
+
+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`.
+
+.. include:: links.inc
diff --git a/doc/source/gitwash/git_links.inc b/doc/source/gitwash/git_links.inc
new file mode 100644
index 0000000..14a76f5
--- /dev/null
+++ b/doc/source/gitwash/git_links.inc
@@ -0,0 +1,54 @@
+.. This (-*- rst -*-) format file contains commonly used link targets
+ 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.
+
+.. NOTE: reST targets are
+ __not_case_sensitive__, so only one target definition is needed for
+ nipy, NIPY, Nipy, etc...
+
+.. git stuff
+.. _git: http://git-scm.com/
+.. _github: http://github.com
+.. _github help: http://help.github.com
+.. _msysgit: http://code.google.com/p/msysgit/downloads/list
+.. _git-osx-installer: http://code.google.com/p/git-osx-installer/downloads/list
+.. _subversion: http://subversion.tigris.org/
+.. _git cheat sheet: http://github.com/guides/git-cheat-sheet
+.. _pro git book: http://progit.org/
+.. _git svn crash course: http://git-scm.com/course/svn.html
+.. _learn.github: http://learn.github.com/
+.. _network graph visualizer: http://github.com/blog/39-say-hello-to-the-network-graph-visualizer
+.. _git user manual: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+.. _git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
+.. _git community book: http://book.git-scm.com/
+.. _git ready: http://www.gitready.com/
+.. _git casts: http://www.gitcasts.com/
+.. _Fernando's git page: http://www.fperez.org/py4science/git.html
+.. _git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html
+.. _git concepts: http://www.eecs.harvard.edu/~cduan/technical/git/
+.. _git clone: http://www.kernel.org/pub/software/scm/git/docs/git-clone.html
+.. _git checkout: http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html
+.. _git commit: http://www.kernel.org/pub/software/scm/git/docs/git-commit.html
+.. _git push: http://www.kernel.org/pub/software/scm/git/docs/git-push.html
+.. _git pull: http://www.kernel.org/pub/software/scm/git/docs/git-pull.html
+.. _git add: http://www.kernel.org/pub/software/scm/git/docs/git-add.html
+.. _git status: http://www.kernel.org/pub/software/scm/git/docs/git-status.html
+.. _git diff: http://www.kernel.org/pub/software/scm/git/docs/git-diff.html
+.. _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 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
+
+.. other stuff
+.. _python: http://www.python.org
+
+.. |emdash| unicode:: U+02014
diff --git a/doc/source/gitwash/git_resources.rst b/doc/source/gitwash/git_resources.rst
new file mode 100644
index 0000000..0fb030f
--- /dev/null
+++ b/doc/source/gitwash/git_resources.rst
@@ -0,0 +1,59 @@
+.. _git-resources:
+
+================
+ git_ resources
+================
+
+Tutorials and summaries
+=======================
+
+* `github help`_ has an excellent series of how-to guides.
+* `learn.github`_ has an excellent series of tutorials
+* The `pro git book`_ is a good in-depth book on git.
+* A `git cheat sheet`_ is a page giving summaries of common commands.
+* The `git user manual`_
+* The `git tutorial`_
+* The `git community book`_
+* `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.
+* Our own `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`_
+* `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
+rules of thumb that other projects have come up with:
+
+* Linus Torvalds on `git management`_
+* Linus Torvalds on `linux git workflow`_ . Summary; use the git tools
+ to make the history of your edits as clean as possible; merge from
+ upstream edits as little as possible in branches where you are doing
+ active development.
+
+Manual pages online
+===================
+
+You can get these on your own machine with (e.g) ``git help push`` or
+(same thing) ``git push --help``, but, for convenience, here are the
+online manual pages for some common commands:
+
+* `git add`_
+* `git branch`_
+* `git checkout`_
+* `git clone`_
+* `git commit`_
+* `git config`_
+* `git diff`_
+* `git log`_
+* `git pull`_
+* `git push`_
+* `git remote`_
+* `git status`_
+
+.. include:: links.inc
diff --git a/doc/source/gitwash/index.rst b/doc/source/gitwash/index.rst
new file mode 100644
index 0000000..4d74ba4
--- /dev/null
+++ b/doc/source/gitwash/index.rst
@@ -0,0 +1,18 @@
+.. _using-git:
+
+Working with *mne-python* source code
+======================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ git_intro
+ git_install
+ following_latest
+ patching
+ git_development
+ git_resources
+
+
diff --git a/doc/source/gitwash/known_projects.inc b/doc/source/gitwash/known_projects.inc
new file mode 100644
index 0000000..2972352
--- /dev/null
+++ b/doc/source/gitwash/known_projects.inc
@@ -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
diff --git a/doc/source/gitwash/links.inc b/doc/source/gitwash/links.inc
new file mode 100644
index 0000000..20f4dcf
--- /dev/null
+++ b/doc/source/gitwash/links.inc
@@ -0,0 +1,4 @@
+.. compiling links file
+.. include:: known_projects.inc
+.. include:: this_project.inc
+.. include:: git_links.inc
diff --git a/doc/source/gitwash/patching.rst b/doc/source/gitwash/patching.rst
new file mode 100644
index 0000000..d312b9d
--- /dev/null
+++ b/doc/source/gitwash/patching.rst
@@ -0,0 +1,134 @@
+================
+ Making a patch
+================
+
+You've discovered a bug or something else you want to change
+in mne-python_ .. |emdash| excellent!
+
+You've worked out a way to fix it |emdash| even better!
+
+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.
+
+.. _making-patches:
+
+Making patches
+==============
+
+Overview
+--------
+
+::
+
+ # tell git who you are
+ git config --global user.email you at 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/mne-tools/mne-python.git
+ # make a branch for your patching
+ cd mne-python
+ 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, send the generated patch files to the `mne-python
+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::
+
+ git config --global user.email you at yourdomain.example.com
+ git config --global user.name "Your Name Comes Here"
+
+#. If you don't already have one, clone a copy of the
+ mne-python_ repository::
+
+ git clone git://github.com/mne-tools/mne-python.git
+ cd mne-python
+
+#. 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 |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::
+
+ 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
+
+ Send these files to the `mne-python mailing list`_.
+
+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 mne-python_ repository on github_ |emdash| :ref:`forking`.
+Then::
+
+ # checkout and refresh master branch from main repo
+ git checkout master
+ git pull 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 at github.com:your-user-name/mne-python.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:: links.inc
diff --git a/doc/source/gitwash/pull_button.png b/doc/source/gitwash/pull_button.png
new file mode 100644
index 0000000..e503168
Binary files /dev/null and b/doc/source/gitwash/pull_button.png differ
diff --git a/doc/source/gitwash/set_up_fork.rst b/doc/source/gitwash/set_up_fork.rst
new file mode 100644
index 0000000..29dde50
--- /dev/null
+++ b/doc/source/gitwash/set_up_fork.rst
@@ -0,0 +1,68 @@
+.. _set-up-fork:
+
+==================
+ Set up your fork
+==================
+
+First you follow the instructions for :ref:`forking`.
+
+Overview
+========
+
+::
+
+ git clone git at github.com:your-user-name/mne-python.git
+ cd mne-python
+ git remote add upstream git://github.com/mne-tools/mne-python.git
+
+In detail
+=========
+
+Clone your fork
+---------------
+
+#. Clone your fork to the local computer with ``git clone
+ git at github.com:your-user-name/mne-python.git``
+#. Investigate. Change directory to your new repo: ``cd mne-python``. Then
+ ``git branch -a`` to show you all branches. You'll get something
+ like::
+
+ * master
+ remotes/origin/master
+
+ 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.
+
+ Now you want to connect to the upstream `mne-python github`_ repository, so
+ you can merge in changes from trunk.
+
+.. _linking-to-upstream:
+
+Linking your repository to the upstream repo
+--------------------------------------------
+
+::
+
+ cd mne-python
+ git remote add upstream git://github.com/mne-tools/mne-python.git
+
+``upstream`` here is just the arbitrary name we're using to refer to the
+main mne-python_ repository at `mne-python github`_.
+
+Note that we've used ``git://`` for the URL rather than ``git@``. The
+``git://`` URL is read only. This means we that we can't accidentally
+(or deliberately) write to the upstream repo, and we are only going to
+use it to merge into our own code.
+
+Just for your own satisfaction, show yourself that you now have a new
+'remote', with ``git remote -v show``, giving you something like::
+
+ upstream git://github.com/mne-tools/mne-python.git (fetch)
+ upstream git://github.com/mne-tools/mne-python.git (push)
+ origin git at github.com:your-user-name/mne-python.git (fetch)
+ origin git at github.com:your-user-name/mne-python.git (push)
+
+.. include:: links.inc
+
diff --git a/doc/source/gitwash/setup.sh b/doc/source/gitwash/setup.sh
new file mode 100644
index 0000000..0a29f15
--- /dev/null
+++ b/doc/source/gitwash/setup.sh
@@ -0,0 +1,3 @@
+python ~/work/src/gitwash/gitwash_dumper.py devel mne-python --repo-name=mne-python --github-user=mne-tools \
+ --project-url=https://github.com/mne-tools/mne-python \
+ --project-ml-url=http://mail.nmr.mgh.harvard.edu/mailman/listinfo/mne_analysis
\ No newline at end of file
diff --git a/doc/source/gitwash/this_project.inc b/doc/source/gitwash/this_project.inc
new file mode 100644
index 0000000..75a8fba
--- /dev/null
+++ b/doc/source/gitwash/this_project.inc
@@ -0,0 +1,5 @@
+.. mne-python
+.. _mne-python: https://github.com/mne-tools/mne-python
+.. _`mne-python github`: http://github.com/mne-tools/mne-python
+
+.. _`mne-python mailing list`: http://mail.nmr.mgh.harvard.edu/mailman/listinfo/mne_analysis
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4b48bf7..996b76e 100755
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -29,5 +29,18 @@ MNE with Python
mne-python
+Working with MNE Python's source code
+=====================================
+
+.. toctree::
+ :maxdepth: 2
+
+ gitwash/git_intro
+ gitwash/git_install
+ gitwash/following_latest
+ gitwash/patching
+ gitwash/git_development
+ gitwash/git_resources
+
* :ref:`search`
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/python-mne.git
More information about the debian-med-commit
mailing list