Library versioning


#1

Right now library versions are strings. They look like "0.1.2" or "0.2".

The library version string is used by the library manager to detect whether there are updates available or not. I think right now there is no “higher/lower version” detection being done, it simply reports a new version being available if the version name changed.

The question is how to handle that in practice. One option would be Semantic Versioning. But there are two issues with that:

  • Library elements should never break compatibility, so there should never be a breaking version increment.
  • New library elements could be considered new features, or they could be considered improvements to the current features. Hard to categorize.

To me, SemVer for libraries doesn’t really make sense. The semantics are unclear in the context of libraries. The only important information conveyed is that the library changed somehow.

That’s why I’d propose using incrementing integers instead of version strings. This could also be a convention only, meaning that it’s still a string in the library (avoiding a format update), but the convention is that the integer is simply incremented on changes.

This is both simpler and does not convey semantics where there aren’t any. Furthermore, it could be automated with a tool, e.g. using a GitHub merge hook.

A third option would be to hash the entire library, but I think that’s a bit more complex than it needs to be.

Opinions?


#2

My preference in this sort of situation is generally to use a timestamp, with some extra checking to make sure that the timestamp still increments if you make an update on a computer with a clock that got set backwards.

If there’s a date that already exists in the format, that could be used, it’s a pretty useful thing to have.

SemVer is really controversial and some people really hate it, and keeping version strings as arbitrary lets people use whatever formatting they want, which can create confusion but also helps when those versions are imported from some other app that might not have the same idea of a version.

I’d be against just replacing the version string with a number though, I think having a human readable version is useful. Libraries could have hundreds of changes as new parts are added.


#3

That’s not true, the version numbers are handled by a Version class which of course provides proper comparison operators :wink:

I agree that the concept of SemVer doesn’t make sense as there are no breaking changes or new features. But maybe we could still express something with meaningful version numbers, for example:

  • 0.x versions: non-mature library element, not proven for correctness/accuracy, may contain issues
  • >= 1.x versions: mature library element, can be used for productive work without additional review
  • incrementing minor version for “small” changes, e.g. only metadata like description/keywords/etc.
  • incrementing major version for “larger” changes, e.g. adding more polygons to footprints, adjusting pad sizes, moving symbol pins, …

But probably it’s not easy to document and enforce the usage of such a system :wink:


#4

I wasn’t talking about the library element versioning. There something semver-looking might even make sense.

Rather, I meant the library itself. And you don’t want to increase the major number of the entire library if you change the polygons of a single library element.