[IPython-dev] Better handling of older notebook versions

[Brian Granger]

Aaron,

On Mon, Jun 18, 2012 at 11:16 PM, Aaron Meurer <asmeurer at gmail.com> wrote:
> Hi.
>
> As you may know, we are planning to migrate our SymPy examples to
> IPython notebooks, and, indeed, we already have some notebooks that we
> intend to ship with the next release.  Currently, we have our
> notebooks saved as version 2 (from IPython 0.12), since IPython 0.13
> has not been released yet.
>
> I played around with the notebook versions, and I found that a version
> 3 notebook doesn't work at all in IPython 0.12, regardless if it has a
> header cell or not (from what I understand, this is the only new
> feature in version 3).  On the other hand, a version 2 notebook is
> automatically converted by IPython git master to version 3 with an
> onscreen warning.

There are a few other features in the v3 notebooks:

* Raw text cells.
* Cell and worksheet metadata.

If your v3 notebook doesn't use these things, and you change the
version number by had in the notebook file, your notebook should work
with 0.12.

> Is there any way that we could make this more friendly to users who
> use our notebooks that we ship.   Currently, we have two options:

Overall, this is going to be tough.  The notebook format is still
evolving rather quickly, so this problem is going to keep coming up.
We want to make the format stable as soon as possible though - we are
not there yet though.

> - Ship version 3 notebooks.  Previously this was not an option because
> version 3 only exists in the development version, but now it is clear
> that you guys will release before we do, so it's actually possible.
> Even so, this may come up again in the future.  Also, if we do this,
> it will obviously alienate any IPython 0.12 users.

The benefit of this approach is that I think you will find that most
people are using the dev/0.13 version of the notebook. Not everyone,
but most are.

> - Ship version 2 notebooks.  If we do this, then anyone who opens the
> notebook with 0.13 will see a warning that the notebook is converted,
> which isn't very friendly since they are not the authors of the
> notebook.   If they save the notebook, it will eliminate the warning,
> but will change it from the released version.  That may not be such a
> bad thing; my main concern is just the initial annoyance/confusion to
> anyone who opens the notebook with the newest version of IPython.

I think this is the safest approach if you can live with the warning.
But remember, it is likely that 0.14 will have additional changes to
the notebook format so this choice won't go away.

The only other option is to try and keep 2 version of every notebook,
but that is a complete pain.

I think my vote would be to distribute 0.12 notebooks for now.

> Any thoughts on this?  Perhaps the read-only notebooks discussed in
> another thread would be the solution to this.  I think something like
> that would be ideal for shipped example notebooks, because it would
> prevent the user from accidentally overriding them, and it might even
> do a "save  as" by default instead (like a template document on the
> Mac).
>
> Aaron Meurer
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev



-- 
Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger at calpoly.edu and ellisonbg at gmail.com