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

[Brian Granger]

Fernando,

A nice lightweight way for dev's to contribute code is to use git
format-patch.  I like how Sympy encourages contributions using this
approach as it is super easy.

I almost think that this document will have the tendency to become a
larger and more involved - and eventually start to overlap with things
like the progit book.  In my experience, the most useful thing for new
devs is having an *exact*, project specific (the real project like
ipython, not gitwash) list of commands that cover %80 of the usage
cases.  Like:

# Get your fork:
git clone git at github.com:ellisonbg/ipython.git

# Create a feature branch
git branch foo
git checkout foo

# edit files, # for each file do:
git add [filename]
git commit
# rinse and repeate

# To post branch to github
git push origin foo

I am thinking like more of a single concise cheatsheet that covers
everything a new user would want.  Basically a "what to type" guide
that fits on 1 page.  The reason I say this is that existing
references like the progit book are so extremely good, there is not
reason to spend time describing the concepts.  Also, I think for a new
user, it will be confusing that the docs are about gitwash rather than
ipython or nipy.  Sorry if this is a bit pessimistic.

Cheers,

Brian


On Sun, Apr 25, 2010 at 1:34 PM, Fernando Perez <fperez.net at gmail.com> wrote:
> 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
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>



-- 
Brian E. Granger, Ph.D.
Assistant Professor of Physics
Cal Poly State University, San Luis Obispo
bgranger at calpoly.edu
ellisonbg at gmail.com