Versioning the file format

[fredrikekre]

I think it would be good to version the file format. I found some previous discussion about this in #131 (comment)

First of all, I should say that we want to avoid any change to the file format, since this would mean adding conversion code to handle old files written before the format change - making the project harder to maintain.

which seems fair, but in the unfortunate case that the format has to change, it would be good to have the format recorded in the file. Pluto would just check that opened files has a format it understand, or error out, instead of adding conversion code.

[fonsp]

Right now it writes the Pluto version to the second line, I thought that this can be used to indirectly version the file format.

Do you mean versioning it more explicitly? i.e. call this version 1, and change to 2 in the future?

[fredrikekre]

Do you mean versioning it more explicitly? i.e. call this version 1, and change to 2 in the future?

Yea exactly, becuse presumable most (all?) Pluto versions can read the same file format? The reason I thought about this is that I thought about making Literate output pluto notebooks, and it would be good to have a specific spec (e.g. version 1) that I can output.

[fonsp]

I thought that the minor version number (minor while in 0.y.z, major after 1.0.0) could indicate the file format version. So then the current spec is 0.11. I didn't plan on any changes to 0.12, but 0.13 will include a package environment, which might require a change. (But I think we can write it in a backwards compatible way.)

You mentioned erroring instead of adding conversion code, but I do think that we should add conversion code on every change from now on. Otherwise you would have to start all your notebooks again. So in that spirit, outputting any current spec will work for all future versions.

[fredrikekre]

Yea that is one idea, but then you couple breaking changes to the package API to the breaking changes in the format. But maybe that is fine.

In any case, it would be nice to not warn about it for the same breaking version, e.g. Pluto v0.11.8 should not complain about a file with v0.11.0 in the header.

[j-fu]

Does it make sense to move the file format and data structure related stuff from Pluto.jl to a PlutoNotebook.jl package which has only few dependencies ? Then Literate.jl, Pluto.jl and possibly other tools which handle notebooks could rely on this one.

[fonsp]

or AbstractNotebook.jl? @pfitzseb

[fonsp]

Let's revisit this if/when we ever need to change the format, or when VS Code wants to share the format @pfitzseb