DOC: reorganize developer docs, use scikit-image as a base for change

1 files changed, 0 insertions, 510 deletions

diff --git a/doc/source/dev/gitwash/development_workflow.rst b/doc/source/dev/gitwash/development_workflow.rst
deleted file mode 100644
index 9561e25f7..000000000
--- a/doc/source/dev/gitwash/development_workflow.rst
+++ /dev/null
@@ -1,510 +0,0 @@
-.. _development-workflow:
-
-====================
-Development workflow
-====================
-
-You already have your own forked copy of the NumPy_ repository, by
-following :ref:`forking`, :ref:`set-up-fork`, you have configured git_
-by following :ref:`configure-git`, and have linked the upstream
-repository as explained in :ref:`linking-to-upstream`.
-
-What is described below is a recommended workflow with Git.
-
-Basic workflow
-##############
-
-In short:
-
-1. Start a new *feature branch* for each set of edits that you do.
-   See :ref:`below <making-a-new-feature-branch>`.
-
-2. Hack away! See :ref:`below <editing-workflow>`
-
-3. When finished:
-
-   - *Contributors*: push your feature branch to your own Github repo, and
-     :ref:`create a pull request <asking-for-merging>`.
-
-   - *Core developers* If you want to push changes without
-     further review, see the notes :ref:`below <pushing-to-main>`.
-     
-This way of working helps to keep work well organized and the history
-as clear as possible.
-
-.. seealso::
-
-   There are many online tutorials to help you `learn git`_. For discussions
-   of specific git workflows, see these discussions on `linux git workflow`_,
-   and `ipython git workflow`_.
-
-.. _making-a-new-feature-branch:
-
-Making a new feature branch
-===========================
-
-First, fetch new commits from the ``upstream`` repository:
-
-::
-
-   git fetch upstream
-
-Then, create a new branch based on the master branch of the upstream
-repository::
-
-   git checkout -b my-new-feature upstream/master
-
-
-.. _editing-workflow:
-
-The editing workflow
-====================
-
-Overview
---------
-
-::
-
-   # hack hack
-   git status # Optional
-   git diff # Optional
-   git add modified_file
-   git commit 
-   # push the branch to your own Github repo
-   git push origin my-new-feature
-
-In more detail
---------------
-
-#. Make some changes. When you feel that you've made a complete, working set
-   of related changes, move on to the next steps.
-
-#. Optional: Check which files have changed with ``git status`` (see `git
-   status`_).  You'll see a listing like this one::
-
-     # On branch my-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")
-
-#. Optional: Compare the changes with the previous version using with ``git
-   diff`` (`git diff`_). This brings up a simple text browser interface that
-   highlights the difference between your files and the previous version.
-
-#. Add any relevant modified or new files using  ``git add modified_file``
-   (see `git add`_). This puts the files into a staging area, which is a queue
-   of files that will be added to your next commit. Only add files that have
-   related, complete changes. Leave files with unfinished changes for later
-   commits.
-
-#. To commit the staged files into the local copy of your repo, do ``git
-   commit``. At this point, a text editor will open up to allow you to write a
-   commit message. Read the :ref:`commit message
-   section<writing-the-commit-message>` to be sure that you are writing a
-   properly formatted and sufficiently detailed commit message. After saving
-   your message and closing the editor, your commit will be saved. For trivial
-   commits, a short commit message can be passed in through the command line
-   using the ``-m`` flag. For example, ``git commit -am "ENH: Some message"``. 
-   
-   In some cases, you will see this form of the commit command: ``git commit
-   -a``. The extra ``-a`` flag automatically commits all modified files and
-   removes all deleted files. This can save you some typing of numerous ``git
-   add`` commands; however, it can add unwanted changes to a commit if you're
-   not careful. For more information, see `why the -a flag?`_ - and the
-   helpful use-case description in the `tangled working copy problem`_.  
-
-#. Push the changes to your forked repo on github_::
-
-      git push origin my-new-feature
-
-   For more information, see `git push`_.
-    
-.. note::
-    
-   Assuming you have followed the instructions in these pages, git will create
-   a default link to your github_ repo called ``origin``.  In git >= 1.7 you
-   can ensure that the link to origin is permanently 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 your own github_ repo. Subsequent push calls
-   are then simplified to the following::
-
-      git push
-   
-   You have to use ``--set-upstream`` for each new branch that you create.
-    
-
-It may be the case that while you were working on your edits, new commits have
-been added to ``upstream`` that affect your work. In this case, follow the
-:ref:`rebasing-on-master` section of this document to apply those changes to
-your branch.
-
-.. _writing-the-commit-message:
-
-Writing the commit message
---------------------------
-
-Commit messages should be clear and follow a few basic rules.  Example::
-
-   ENH: add functionality X to numpy.<submodule>.
-
-   The first line of the commit message starts with a capitalized acronym
-   (options listed below) indicating what type of commit this is.  Then a blank
-   line, then more text if needed.  Lines shouldn't be longer than 72
-   characters.  If the commit is related to a ticket, indicate that with
-   "See #3456", "See ticket 3456", "Closes #3456" or similar.
-
-Describing the motivation for a change, the nature of a bug for bug fixes or
-some details on what an enhancement does are also good to include in a commit
-message.  Messages should be understandable without looking at the code
-changes.  A commit message like ``MAINT: fixed another one`` is an example of
-what not to do; the reader has to go look for context elsewhere.
-
-Standard acronyms to start the commit message with are::
-
-   API: an (incompatible) API change
-   BENCH: changes to the benchmark suite
-   BLD: change related to building numpy
-   BUG: bug fix
-   DEP: deprecate something, or remove a deprecated object
-   DEV: development tool or utility
-   DOC: documentation
-   ENH: enhancement
-   MAINT: maintenance commit (refactoring, typos, etc.)
-   REV: revert an earlier commit
-   STY: style fix (whitespace, PEP8)
-   TST: addition or modification of tests
-   REL: related to releasing numpy
-
-
-.. _asking-for-merging:
-
-Asking for your changes to be merged with the main repo
-=======================================================
-
-When you feel your work is finished, you can create a pull request (PR). Github
-has a nice help page that outlines the process for `filing pull requests`_. 
-
-If your changes involve modifications to the API or addition/modification of a
-function, you should initiate a code review. This involves sending an email to
-the `NumPy mailing list`_ with a link to your PR along with a description of
-and a motivation for your changes.
-
-.. _rebasing-on-master:
-
-Rebasing on master
-==================
-
-This updates your feature branch with changes from the upstream `NumPy
-github`_ repo. If you do not absolutely need to do this, try to avoid doing
-it, except perhaps when you are finished. The first step will be to update
-the remote repository with new commits from upstream::
-
-   git fetch upstream
-
-Next, you need to update the feature branch::
-
-   # go to the feature branch
-   git checkout my-new-feature
-   # make a backup in case you mess up
-   git branch tmp my-new-feature
-   # rebase on upstream master branch
-   git rebase upstream/master
-
-If you have made changes to files that have changed also upstream,
-this may generate merge conflicts that you need to resolve. See
-:ref:`below<recovering-from-mess-up>` for help in this case.
-
-Finally, remove the backup branch upon a successful rebase::
-
-   git branch -D tmp
-
-
-.. note::
-
-   Rebasing on master is preferred over merging upstream back to your
-   branch. Using ``git merge`` and ``git pull`` is discouraged when
-   working on feature branches.
-
-.. _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 my-feature-branch
-
-   8630830 my-feature-branch@{0}: commit: BUG: io: close file handles immediately
-   278dd2a my-feature-branch@{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d
-   26aa21a my-feature-branch@{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 my-feature-branch@{2}
-
-If you didn't actually mess up but there are merge conflicts, you need to
-resolve those.  This can be one of the trickier things to get right.  For a
-good description of how to do this, see `this article on merging conflicts`_.
-
-
-Additional things you might want to do
-######################################
-
-.. _rewriting-commit-history:
-
-Rewriting commit history
-========================
-
-.. note::
-
-   Do this only for your own feature branches.
-
-There's an embarrassing 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 ``master`` 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>`.
-
-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:
-https://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
-``https://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@github.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 my-feature-branch # 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.
-
-Backporting
-===========
-
-Backporting is the process of copying new feature/fixes committed in
-`numpy/master`_ back to stable release branches. To do this you make a branch
-off the branch you are backporting to, cherry pick the commits you want from
-``numpy/master``, and then submit a pull request for the branch containing the
-backport.
-
-1. First, you need to make the branch you will work on. This needs to be
-   based on the older version of NumPy (not master)::
-
-    # Make a new branch based on numpy/maintenance/1.8.x,
-    # backport-3324 is our new name for the branch.
-    git checkout -b backport-3324 upstream/maintenance/1.8.x
-
-2. Now you need to apply the changes from master to this branch using
-   `git cherry-pick`_::
-
-    # Update remote
-    git fetch upstream
-    # Check the commit log for commits to cherry pick
-    git log upstream/master
-    # This pull request included commits aa7a047 to c098283 (inclusive)
-    # so you use the .. syntax (for a range of commits), the ^ makes the
-    # range inclusive.
-    git cherry-pick aa7a047^..c098283
-    ...
-    # Fix any conflicts, then if needed:
-    git cherry-pick --continue
-
-3. You might run into some conflicts cherry picking here. These are
-   resolved the same way as merge/rebase conflicts. Except here you can
-   use `git blame`_ to see the difference between master and the
-   backported branch to make sure nothing gets screwed up.
-
-4. Push the new branch to your Github repository::
-
-    git push -u origin backport-3324
-
-5. Finally make a pull request using Github. Make sure it is against the
-   maintenance branch and not master, Github will usually suggest you
-   make the pull request against master.
-
-.. _pushing-to-main:
-
-Pushing changes to the main repo
-================================
-
-*This is only relevant if you have commit rights to the main NumPy repo.*
-
-When you have a set of "ready" changes in a feature branch ready for
-NumPy's ``master`` or ``maintenance`` branches, you can push
-them to ``upstream`` as follows:
-
-1. First, merge or rebase on the target branch.
-
-   a) Only a few, unrelated commits then prefer rebasing::
-
-        git fetch upstream
-        git rebase upstream/master
-
-      See :ref:`rebasing-on-master`.
-
-   b) If all of the commits are related, create a merge commit::
-
-        git fetch upstream
-        git merge --no-ff upstream/master
-
-2. Check that what you are going to push looks sensible::
-
-        git log -p upstream/master..
-        git log --oneline --graph
-
-3. Push to upstream::
-
-        git push upstream my-feature-branch:master
-
-.. note:: 
-
-    It's usually a good idea to use the ``-n`` flag to ``git push`` to check
-    first that you're about to push the changes you want to the place you
-    want.
-
-
-.. include:: git_links.inc