numpy/numpy — pull request #5332 by rnelsonchem (2014-12-01 04:37:11+00:00)
Title: DOC: Reorganization request for Development Workflow docs

As a new contributor, I tried to follow the Development Workflow documentation; however, I found this page to be a little confusing in places. I've reorganized things in a way that seems to make more sense to me now that I've made a code submission via pull request. I'm not a git wizard, so I would appreciate any feedback in case I messed things up. Below are the major changes and remaining questions that I'd like to address. I'm happy to roll a lot of this back, but this addresses some issues I had as a newcomer.

Major changes:
* Move the rebasing section out of the basic workflow. The first sentence in this section advises not to do this, so it is unclear why this would be a basic workflow issue. Is there another reason that this is important? Perhaps to make sure there are no merge conflicts, but if so, it is not clear to a beginner.
* Also separate out the problems from the rebasing section. It seems like this covers (or could cover) more than just rebasing, so it made sense to make it a separate section.
* Removed core dev notes from the basic workflow. I don't imagine that the core devs need to run through the basic workflow checklist all that often, and these are not commands that a beginner needs to worry about. (Or they probably can't do without commit rights...?)
* Moved some of the discussion of git push from the New Branch section to the end of the Editing section. It just seemed more natural that you would need to worry about pushing to a remote repo after you've done all of your changes.
* Renamed a few links and removed a broken one (Matthew Brett's NiPy comparison link)

Questions:
* The Asking for a Merge section suggests both code reviews via the mailing list and pull requests. Is there a reason to prefer one over the other? Should pull requests only be filed for opened issues? It might be nice to include that.
* I tried to build the documentation in a fresh conda Python 3.4 environment with the minimal dependencies. However, it choked right away because it could not find the plot_directive extension. Of course, installing Matplotlib into this environment fixed the error. However, there is nothing about this dependency in doc/HOWTO_BUILD_DOCS.rst.txt. I'm happy to add something to this document, but I'm not sure that you want to recommend MPL as a Numpy dependency. Is there an alternate method to finding this extension that should be included in the docs?