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:
When a new commit is pushed, this will be automatically updated:
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.
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:
But other things that would be good subjects of the YTEP process:
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?