[yt-dev] YTEPs: yt Enhancement Proposals

[Matthew Turk]

Hi all,

There's been some discussion of planning documents.  For a while I
thought we could use JIRA for this, but I think it's time to put that
plan on hold, particularly in light of the discussion a couple weeks
ago where the strong sentiment of using Sphinx/ReST (i.e., something
we *know*) was expressed.

So I'd like to present YTEPs: yt Enhancement Proposals.  I see this as
a place for evolving design documents, or for design documents that
describe how things are being implemented moving forward.  This means
instead of having a mailing list post serve as the primary reference
point for something, we'll have a repository of documents that get
automatically built into documentation, which can be discussed via PR
and via mailing list and iterated on.  Other projects such as NumPy,
Matplotlib, IPython, Cython and Python itself use enhancement
proposals to describe proposed major changes and to leave a record of
what has been done and how it was implemented.

I know this sounds like a lot of project planning and whatnot, but I
think this could be very useful particularly as we transition to yt
3.0, where a lot of design decisions have been made or need to be
made, and where we are hoping to build something sustainable.

Here's the repository I've created:

https://bitbucket.org/yt_analysis/ytep/

When a new commit is pushed, this will be automatically updated:

http://yt.readthedocs.org/projects/ytep/en/latest/

This also includes information about why you would write a YTEP, how
you would do so, and what to do once you have.

I have written my first YTEP based on the IO chunking mechanism that
I've alluded to here in the past.  I've issued a PR, but I hope that
things like this can be the subject of discussion either on the
mailing list or in the PR to ensure that the YTEP covers everything
that it needs to.  These can be updated over time, as well, after they
are initially accepted.

https://bitbucket.org/yt_analysis/ytep/pull-request/1/adding-ytep-0001-data-chunking/diff

Once this has been accepted, the YTEP repo will be automatically updated.

I'll commit to writing YTEPs for other aspects of 3.0 as well:

 * Multiple particle, multiple fluid access
 * Geometry handling
 * Coordinate systems

But other things that would be good subjects of the YTEP process:

 * Initial conditions API
 * The GDF
 * Changing Halos to all be lightweight
 * Switching the order of arguments of projections
 * Switching Reason to use IPython

I would like to encourage people who are working on enhancements or
changes that have large, user-facing changes or components that would
benefit from input on design or implementation details submit YTEPs.
I'd also like to encourage that if you are reviewing a pull request or
changeset that would benefit from this process, you ask the submitter
to write a YTEP.  The overhead is relatively minimal, and I think at
this time we have grown as a project to the point that keeping a
record of design thoughts is a responsibility we have to our
community.

Does this sound like an appropriate step?  Does this implementation,
template and setup sound acceptable to everyone else?

Best,

Matt