<div dir="ltr">I like Cameron's idea a ton. We do have to draw a line somewhere on these docs or else they will never get done. I really like the idea of allowing changes into the development (here yt-3.0) branch with minimal/some docs, but an absolute hard deadline when it comes to changes getting into stable releases. I also think we need to establish some sort of guideline for minimally acceptable documentation otherwise we risk losing the bridge to the rest of the developers.<div>
<br></div><div>Britton</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Feb 7, 2014 at 4:31 PM, Cameron Hummels <span dir="ltr"><<a href="mailto:chummels@gmail.com" target="_blank">chummels@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">Hey guys,<div><br></div><div>I'm +1 on this--no strings attached. I totally agree with what Matt has said above, as I do see the need to get unit refactor into the main development line, since much of the current development has taken place there as of late.</div>
<div><br></div><div>I think Matt's suggestions for blockers on the docs are spot-on, and I applaud the efforts that he has already made to get them moving. I understand not having a full docs refactor immediately, in a desire to get the code available to the userbase. I'm very happy to review stuff, but I'm afraid I cannot be much help in authorship given that I have little experience with the new refactor.</div>
<div><br></div><div>The only small thing that I might suggest is to have some sort of timeline, even if it is a loose one, on when we can complete the narrative docs, the SPH smoothing docs, and bringing the docs fully up to speed with 3.0. I realize this may take some time, but I think it is important to not get into a deficit on this, as it will likely just grow with time (I say this as an experienced procrastinator). Maybe before 3.0 is officially released to the community as a stable version? Maybe shortly after? I'd be interested in other's thoughts on this and I'm flexible on this.</div>
<div><br></div><div>Thanks, Matt.<br><br>Cameron<br><br><br></div>
</div><div class="gmail_extra"><div><div class="h5"><br><br><div class="gmail_quote">On Fri, Feb 7, 2014 at 12:41 PM, Matthew Turk <span dir="ltr"><<a href="mailto:matthewturk@gmail.com" target="_blank">matthewturk@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div>On Fri, Feb 7, 2014 at 2:37 PM, Nathan Goldbaum <<a href="mailto:nathan12343@gmail.com" target="_blank">nathan12343@gmail.com</a>> wrote:<br>
> On Fri, Feb 7, 2014 at 11:33 AM, Matthew Turk <<a href="mailto:matthewturk@gmail.com" target="_blank">matthewturk@gmail.com</a>> wrote:<br>
>> On Fri, Feb 7, 2014 at 2:31 PM, Nathan Goldbaum <<a href="mailto:nathan12343@gmail.com" target="_blank">nathan12343@gmail.com</a>> wrote:<br>
>>> One issue with recommending that people stay on the current yt-3.0 tip<br>
>>> is that there are a number of bugs (the most serious are related to<br>
>>> field detection), that are fixed in unitrefactor.<br>
>>><br>
>>> The API changes in 3.0 we've been planning for a long time (see the<br>
>>> YTEP repo) were always going to be a bit painful and I think we're<br>
>>> finally at the point where that starts to become a concern.<br>
>>><br>
>>> So long as there is a big docs push on a relatively short timescale,<br>
>>> I'd be +1 on the approach Matt suggests.<br>
>>><br>
>>> Matt, where is the documentation you are Britton have started work on?<br>
>>> I don't see it in MatthewTurk/yt.<br>
>><br>
>> MatthewTurk/yt-units@30docs<br>
>><br>
><br>
> What about the stumbling blocks document?<br>
<br>
</div>doc/source/yt3differences.rst<br>
<br>
Just added a few more items to it.<br>
<div><div><br>
><br>
>>><br>
>>> On Fri, Feb 7, 2014 at 11:21 AM, John Zuhone <<a href="mailto:jzuhone@gmail.com" target="_blank">jzuhone@gmail.com</a>> wrote:<br>
>>>> I guess I see both sides of this. Part of me wants to say that we<br>
>>>> should mark a "stable-ish" alpha/beta/wherever we are version of 3.0<br>
>>>> right before the unit refactoring, and encourage people who use 3.0<br>
>>>> already to stop there for now. I suppose the objection to this is what<br>
>>>> happens when bugs in that version are found, but we also have to think<br>
>>>> about fixing potentially any bug now in light of the new units<br>
>>>> functionality. I'm not myself going to be doing any development from<br>
>>>> this point that doesn't assume the new field system and units, so I<br>
>>>> don't have to change it later.<br>
>>>><br>
>>>> However, I am not particularly religious on what direction we should<br>
>>>> go with this, so count me as a solid 0.<br>
>>>><br>
>>>> On Fri, Feb 7, 2014 at 1:47 PM, Matthew Turk <<a href="mailto:matthewturk@gmail.com" target="_blank">matthewturk@gmail.com</a>> wrote:<br>
>>>>> Hi everyone,<br>
>>>>><br>
>>>>> I've done a lot of thinking and talking with people about the idea of<br>
>>>>> merging the units stuff into the mainline yt 3.0 branch.<br>
>>>>><br>
>>>>> There are clear advantages to doing this: people who want to use SPH<br>
>>>>> smoothing would be able to get it from the primary repository, PRs<br>
>>>>> could be done through that repository, and the access to new things<br>
>>>>> would be considerably easier. More public development and review<br>
>>>>> could happen; while the development already *is* public, it's out of<br>
>>>>> view in my fork of yt. This is not productive.<br>
>>>>><br>
>>>>> But the development of yt is not the point of yt. Using yt to enable<br>
>>>>> scientific discovery is the point of yt.<br>
>>>>><br>
>>>>> In many ways, the units refactor will enable more scientific<br>
>>>>> discovery. But it's not ready. There are people using yt-3.0<br>
>>>>> *already* (prime example: <a href="http://nickolas1.com/d3test2/" target="_blank">http://nickolas1.com/d3test2/</a> ) to do really<br>
>>>>> cool science in ways that they can't with 2.x. And they're doing this<br>
>>>>> with a yt that *mostly* works like the 2.x branch, with the same field<br>
>>>>> names and units and all of that, so the docs *mostly* apply.<br>
>>>>><br>
>>>>> The units refactor, if merged in, would pull the rug *completely* out<br>
>>>>> from under them. And there's no safety net. There's a web of YTEPs<br>
>>>>> and PR comments and notebooks posted to mailing lists, but there's no<br>
>>>>> place they can go and see, "Hey, this worked before, why isn't it<br>
>>>>> now?" And that's not okay.<br>
>>>>><br>
>>>>> I've long put off writing documentation, and honestly, I could come up<br>
>>>>> with lots more reasons to put it off. But I started on Wednesday<br>
>>>>> actually writing things down in earnest, and I think that needs to be<br>
>>>>> the next big push, which I am committed to doing. Yeah, it's not that<br>
>>>>> fun always. Especially since things *are* still changing. But it's<br>
>>>>> not fair -- and it is certainly not in the spirit of *extreme empathy*<br>
>>>>> -- to just change things.<br>
>>>>><br>
>>>>> But I also want new development to continue. And so I want a balance<br>
>>>>> to be struck. I'd like to enumerate the items that are necessary for<br>
>>>>> documentation so that we can merge it in. I think these are as<br>
>>>>> follows:<br>
>>>>><br>
>>>>> * All notebooks should be ported to the 3.0 docs and unit-refactor style<br>
>>>>> * API documentation has to be able to be compiled<br>
>>>>> * At a *bare* minimum, a list of stumbling blocks has to be included<br>
>>>>> for moving to 3.0. Britton and I have started on this and made very<br>
>>>>> good progress.<br>
>>>>> * We need a bookmark or tag to be included in the repo *pre*-refactor.<br>
>>>>> * Cookbook recipes must work (I think they mostly do now)<br>
>>>>><br>
>>>>> Things I don't think we need to do before merging:<br>
>>>>><br>
>>>>> * Completely update 100% of the narrative docs<br>
>>>>> * Document how to add smoothing fields, as I believe this API is in flux<br>
>>>>> * Describe the underlying methods in great, extensive detail for the<br>
>>>>> new frontends<br>
>>>>> * A full, complete review of the docs like we did in advance of 2.6<br>
>>>>><br>
>>>>> As a thought, why don't we treat documentation the way we treat code?<br>
>>>>> Within the project, it seems we're comfortable committing and<br>
>>>>> submitting work-in-progress code, but not docs. In the past, perhaps<br>
>>>>> this was because the PRs and repos were separate. They aren't<br>
>>>>> anymore.<br>
>>>>><br>
>>>>> How does this proposal for the merge sound? Please render an opinion,<br>
>>>>> as I'd like to have this settled before the early part of next week.<br>
>>>>><br>
>>>>> Thanks everyone,<br>
>>>>><br>
>>>>> Matt<br>
>>>>> _______________________________________________<br>
>>>>> yt-dev mailing list<br>
>>>>> <a href="mailto:yt-dev@lists.spacepope.org" target="_blank">yt-dev@lists.spacepope.org</a><br>
>>>>> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
>>>><br>
>>>><br>
>>>><br>
>>>> --<br>
>>>> John ZuHone<br>
>>>><br>
>>>> Postdoctoral Researcher<br>
>>>> NASA/Goddard Space Flight Center<br>
>>>><br>
>>>> <a href="mailto:jzuhone@gmail.com" target="_blank">jzuhone@gmail.com</a><br>
>>>> <a href="mailto:john.zuhone@nasa.gov" target="_blank">john.zuhone@nasa.gov</a><br>
>>>> _______________________________________________<br>
>>>> yt-dev mailing list<br>
>>>> <a href="mailto:yt-dev@lists.spacepope.org" target="_blank">yt-dev@lists.spacepope.org</a><br>
>>>> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
>>> _______________________________________________<br>
>>> yt-dev mailing list<br>
>>> <a href="mailto:yt-dev@lists.spacepope.org" target="_blank">yt-dev@lists.spacepope.org</a><br>
>>> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
>> _______________________________________________<br>
>> yt-dev mailing list<br>
>> <a href="mailto:yt-dev@lists.spacepope.org" target="_blank">yt-dev@lists.spacepope.org</a><br>
>> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
> _______________________________________________<br>
> yt-dev mailing list<br>
> <a href="mailto:yt-dev@lists.spacepope.org" target="_blank">yt-dev@lists.spacepope.org</a><br>
> <a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
_______________________________________________<br>
yt-dev mailing list<br>
<a href="mailto:yt-dev@lists.spacepope.org" target="_blank">yt-dev@lists.spacepope.org</a><br>
<a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div></div></div><span class="HOEnZb"><font color="#888888">-- <br>Cameron Hummels<div>Postdoctoral Researcher</div><div>Steward Observatory</div><div>University of Arizona</div>
<div><a href="http://chummels.org" target="_blank">http://chummels.org</a></div>
</font></span></div>
<br>_______________________________________________<br>
yt-dev mailing list<br>
<a href="mailto:yt-dev@lists.spacepope.org">yt-dev@lists.spacepope.org</a><br>
<a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br>
<br></blockquote></div><br></div>