search

G-Node / nix

Neuroscience information exchange format
https://readthedocs.org/projects/nixio/
Other
66 stars 36 forks source link

Description of library version compatibility rules #677

Closed achilleas-k closed 7 years ago

achilleas-k commented 7 years ago

In addition to the compatibility rules for file format versions, we should also explain how library version compatibility works.

Some aspects of this we haven't discussed in detail, so let me know if you agree with the rules.

gicmo commented 7 years ago

Cool! Thanks for doing that. I think the section about the API is fine. Question is if we just don't want to explicitly adopt semantic versioning, which I think is basically what is written down now (I haven't read through the whole serm ver doc though, there might be some things we see differently). One thing I am hesitant about is how we "link" API and file version. Because you can clearly do a lot of format changes and have no API change and I am not sure I wanna force an API change for a format change. Storage modules (read 'backends', e.g. hdf5, fs backend) could in theory also life outside the NIX source root (and be dynamically loaded). OTOH I also clearly see the point that if we make changes to the HDF5 backend we need a new release at some point, but that could still be a patch (Z) release bump only. I think it is probably a good idea to separate the API paragraph and the file version paragraph and have a different paragraph explaining the link of the two (maybe after having some more discussions about it).

achilleas-k commented 7 years ago

I agree that the file and lib versions shouldn't be linked, but it's kinda hard for them to be completely independent. While I was writing this, the lib version Y value change only described API changes and not file format revisions. The problem with that scheme though is that if we have a minor file format change (e.g., the boolean change), the library should be updated to reflect it. If the boolean update was only a bump in the Z value, it would kinda make it look like a very small change (bugfix, or minor patch) but in reality, it was a change that the library unable to open old files in read-write mode.

jgrewe commented 7 years ago

I was also confused when I read the Y api version change to occur at format changes. But I do not see how they can possibly be kept completely separated.

One could argue that we have the format version for changes in the format that do only require patch changes in the api. On the other hand, making only a z change in api version suggests that everything is fine and the binding libs do not change. Long story short, I agree with the terms stated in the doc.

gicmo commented 7 years ago

@jgrewe good point. In your example actual bindings would actually just work. But reimplementations (like pycore of nixpy) would need adjustment; but the changes we introduced to the file opening should actually handle all these cases fine. From experience I am also doubting that even our bindings actually follow nix development much (see e.g. nix-mx and nix-java) so maybe we would make a bigger file format changes but still not get around to update the bindings because we dont have time. Would we want a new major release and have no bindings for it? I therefore still think we should just strip the file version and API version link out and decided on a case-by-case basis what we do. Most likely what exactly is written there now. We could (should) put this considerations into a maintainers guide (together with the release instructions).

achilleas-k commented 7 years ago

I kept a mention of file format versions for the X major value. I think we should at least keep that there since e.g., NIX file format 2.0.0 should come with a NIX lib version 2.0.0.