[IPython-dev] Gitwash: a git/github workflow document for review

[Fernando Perez]

Hi all,

Matthew Brett has just finished writing up a first draft of a simple,
*self-contained* description of how to download, contribute to and
develop a github-hosted project:

- rendered version of the docs: https://cirl.berkeley.edu/mb312/gitwash/
- source repo: http://github.com/matthew-brett/gitwash

We expect to use this to help the nipy project transition from bzr to
git/github, and also to use it for IPython.  So we'd like to submit it
for further feedback here, in your minds replace the hypothetical
'gitwash' with 'IPython' and that's what we would ultimately use as
our intro document for anyone wanting to work from the sources.

This document should:

- be easy to read in a short amount of time, without users new to
git/github having to read 10 different Git tutorials (which may be
very good, but may also overwhelm a newcomer with information that he
or she initially doesn't know how to prioritize for relevance).

- enable a newcomer to the project to download it with no
complications, but to later transition to doing development with a
minimal threshold.

- enable someone who knows they want to develop (or existing
ipython/nipy developers) to get started right away.


Obviously once people are comfortable with the basics they will want
(and should) read some of the excellent git/gh documentation out
there.  But at that point they will be in a position to digest it and
benefit from it, which may not be true at the raw start.

If the document fails in *any* way at this, please let us know.  Any
lack of clarity, any confusion, any dark spots should be pointed out,
we want to make this as painless as possible for everyone involved.

Cheers,

f