Versioning inconsistency in arduino-lmic libraries


#1

@matthijs can you comment on the following?:

I compared arduino-lmic on github (https://github.com/matthijskooijman/arduino-lmic)
with the same library on PlatformIO (Registry ID: 852).

The library.properties files on GitHub and PlatformIO are identical (except for line endings PC/Unix style),
both have “version=1.5.0+arduino-1”. This indicates that the libraries on GitHub and PlatformIO are identical.
However, the library sources are not identical and the examples are also not identical.
The sources and examples are different and the ones on Github appear newer.

It looks like the library sources were updated but the version number and library.properties file were not.
My assumption is that when the library was updated on GitHub, PlatformIO was not able to detect the update because library.properties has not changed.

Having identical versions gives the impression that the “IBM LMIC framework” / “arduino-lmic” libraries on GutHub and PlatformIO are identical but they are different. This is confusing and should be fixed.

And the fix is simple: no source code changes are required, just the meta file library.properties needs to be updated.

Contents of library.properties:

name=IBM LMIC framework
version=1.5.0+arduino-1
author=IBM
maintainer=Matthijs Kooijman matthijs@stdin.nl
sentence=Arduino port of the LMIC (LoraWAN-in-C, formerly LoraMAC-in-C) framework provided by IBM.
paragraph=Supports SX1272/SX1276 and HopeRF RFM92/RFM95 tranceivers
category=Communication
url=http://www.research.ibm.com/labs/zurich/ics/lrsc/lmic.html
architectures=*


BIG ESP32 / SX127x topic part 1
(Mikael Falkvidd) #2

Yes, the library was updated without changing the version. It was discussed here: Full Arduino Mini LoraWAN and 1.3uA Sleep Mode


#3

I hope @matthijs can soon fix this issue because PlatformIO cannot provide the latest lmic library version mainly because the library version has not been updated by the author.


(Matthijs Kooijman) #4

I wasn’t planning to bump the version on every commit, but only tag releases on significant updates. However, since I’m not getting around to working on LMIC as much as I would want, I just pushed a new tag from the current master, so at least the latest version can be made available. Let me know if that works to update the PlatformIO version?


#5

It’s working now:

Library Storage: /opt/TTGOLora32/.piolibdeps
Updating ESP8266_SSD1306 @ 3.2.7 [Up-to-date]
Updating IBM LMIC framework @ 1.5.0+arduino-1[1.5.0+arduino-2]
Uninstalling IBM LMIC framework @ 1.5.0+arduino-1: [OK]
Looking for IBM LMIC framework library in registry
Found: http://platformio.org/lib/show/852/IBM LMIC framework
LibraryManager: Installing id=852 @ 1.5.0+arduino-2
Downloading [####################################] 100%
Unpacking [####################################] 100%
IBM LMIC framework @ 1.5.0+arduino-2 has been successfully installed!


#6

@matthijs Thanks for updating.

No success with PlatformIO yet (bummer!).
PlatformIO uses Semantic Versioning and your library version is not compatble with that.
PlatformIO may need some time for synchronisation, but I think that is not the issue here.
I am not aware about the internals of how PlatformIO detects and provides new versions of libraries, but I do suspect that the version format of your library may be the culprit here.

With all respect for your work on the Arduino LMIC library, I would like to address the following:

Your arduino-lmic repository is used by many people as a ‘reference’ LMiC implementation for the Arduino framework (for different platforms and boards).
You are not publishing and maintaining stable releases so people will just grab the latest revision from your repository.
From library user perspective the library.properties meta file is the only reliable and tools supported reference where people (and tools) can check the version of the library code that they are using.

By lack of published stable releases (unique URL per release) users and tools will automatically regard the Head of your repository’s Master branch as the current ‘stable version’ (whether correct or not, they just don’t have any other option).

I would like to suggest to:

  • Use Semantic Versioning (see https://semver.org/).
  • Use the semantic versioning format (don’t use any alphanumeric tags in the version).
  • If there are any library specific needs that you feel should be reflected in the version by adding alphanumeric tags, do not misuse the version for that. If there is any such need a separate library should be created instead (otherwise just incrementing the version should suffice).
  • Change the name of your arduino-lmic library from “IBM LMIC framework” to “LMIC-Arduino” which stands for ‘the LMIC library for the Arduino platform’. This better reflects the purpose of the library than the current generic name. No spaces in the name. LMIC first because that is the main subject.
    (While it is possible to use spaces in library names, I do suggest not to use spaces in library names. This provides better consistency because easier to handle and easier to have directory names identical to the library name.)
  • Update the version and library.properties file with every code increment (with any change).
  • Preferable: provide/publish stable releases in addition to ‘the latest and greatest’ Head revision of the Master branch.
  • A possible option for version numbers would be to use even PATCH numbers for stable releases and uneven PATCH numbers for other code updates (this seems to be a common use in the Linux community).

Strong advice for other developers:

  • When you fork a library and make it publicly available (e.g. on GitHib),
    Do change the library name of your forked library and update library.properties accordingly.
    This will save your users from problems, wasting time, headaches and frustration.

.
Note: Even when the current library version ‘number’ will work properly with PlatformIO, my above advice and suggestions still hold.


#7

That’s weird, I have a different experience.
Using VSCode with PlatformIO IDE version 0.8.0 (Home 0.3.2, Core 3.5.0b6) on Windows 10.

The library manifest shows the new version but the version drop-down still only shows 1.5.0+arduino-1 and when I manually install it I still get the old version and the same happens when I add a lib_deps library dependency in platformio.ini.


#8

That library version 1.5.0+arduino-2 looks like an attempt to some kind of SQL-injection attack. :wink:


#9

I just went to the project root and did a pio lib update

It pulled the new version right away.


#10

When I do that nothing happens, it says 1.5.0+arduino-1 is latest.

pio lib update capture


#11

Strange… I’ve picked up another project and did an update:

Library Storage: /opt/TTNSTM32ABP/.piolibdeps
Updating IBM LMIC framework @ 1.5.0+arduino-1[1.5.0+arduino-2]
Uninstalling IBM LMIC framework @ 1.5.0+arduino-1: [OK]
Looking for IBM LMIC framework library in registry
Found: http://platformio.org/lib/show/852/IBM LMIC framework
LibraryManager: Installing id=852 @ 1.5.0+arduino-2
Downloading [####################################] 100%
Unpacking [####################################] 100%
IBM LMIC framework @ 1.5.0+arduino-2 has been successfully installed!

It is working for me.

Do you have any proxy/caching server? And deleting the .piolibdeps directory and doing a clean install?


#12

I already tried those options. None give any different result. Even when creating a new project, I only get the old ‘1.5.0+arduino-1’ version. (No proxy/caching server here.)
I may be mistaking but I suspect that (part of) PlatformIO (tooling) has difficulty in properly handling the (rather unusual) library version.

If I would have to guess the correct version according to Semantic Versioning rules, I would interprete “1.5.0+arduino-2” as version 1.5.0 (not knowing what to do with the remaining “+arduino-2”).

It appears that you are running on Linux or Mac OS (Atom or VSCode?). So the implementation of the underlying tooling will be different which probably contributes to our different experiences and different levels of success.


#13

Now, one day after the library version was updated, it also works correctly here.
When referencing the “IBM LMIC framework” it now properly downloads version 1.5.0+arduino-2.
So the problems I was facing yesterday (after the library version was updated) appear to be related to crawler/caching updating stuff.


#14

@matthijs

Updating the library version in library.properties has fixed the problem (explained below). :+1:

I strongly suggest:

.
Background Information

PlatformIO uses metadata file library.json to describe libraries. It is similar to library.properties from the Arduino IDE but has more fields. PlatformIO can also read the library.properties file from Arduino libraries.
PlatformIO updates a library only if the version has changed so updating the version with every release is a must.

You can search for a library in the PlatformIO Library Registry.


(Matthijs Kooijman) #15

@bluejedi, thanks for your suggestions. Let me give you a bit more background on the current situation.

DO UPDATE the library version and library.properties with every release
(see below why this is a must).

This is pretty much what I’m doing already, except that I haven’t gotten around to actually doing releases a lot (and updating the version number on every commit is not what should happen IMHO).

In your first post, you say:

Update the version and library.properties file with every code increment (with any change).
Preferable: provide/publish stable releases in addition to ‘the latest and greatest’ Head revision of the Master branch.

How do you suggest to identify these stable releases? Through different branches of version numbers and using documentation to indicate which are stable?

A possible option for version numbers would be to use even PATCH numbers for stable releases and uneven PATCH numbers for other code updates (this seems to be a common use in the Linux community).

FWIW, I don’t think Linux does that anymore, they just use a x.x.0 release for new features, and then x.x.1 etc for bugfix-only releases (which could be useful here as well, except that does not mesh well with doing a release on every commit, but I wasn’t planning to do that anyway).

The URL iThe URL in library.properties is a dead link, the page does not exist anymore.
It is better to change URL to https://github.com/matthijskooijman/arduino-lmic1
(in conformance with the Arduino IDE 1.5 Library Specification).

Agreed, I just pushed this change.

The current library version 1.5.0+Arduino-2 is unclear and puzzling (it has more meaning to you than to others). Using Semantic Versioning is a best practice. It will make things simpler and more clear and is also what PlatformIO suggests. Please use Semantic Versioning.

The background of this version number is that this is an Arduino-specific port of an upstream LMIC version. Since LMIC itself could release new versions, and I might also release multiple versions for one upstream LMIC version, this needed an extra level of versioning. To be explicit, I added the +arduino-x, though it might have been more semver (but less explicit) to just add .x instead (e.g. 1.5.0.1.

I’m still planning to revamp the entire LMIC-repo and create an upstream repo that includes the Arduino-specific files, which completely removes this problem (since there will be only one repository doing releases). Until then, I’ll probably stick to the current versioning scheme (since I do not think it is actually breaking anything, other than people’s understanding).


(Matthijs Kooijman) #16

I also just did this.


#17

Great, thanks! :+1:

My first suggestion of updating the version with every commit, is actually bad and not the preferred way. I made the suggestion because there currently are no ‘real release versions’ and when the version is not updated PlatformIO will not notice any changes and not update the library data on PlatformIO accordingly.
Preferred would be to work with real releases, but my GitHub experience is too shallow for giving suggestions on how that could be best implemented for a GitHub repo.
On one hand you want different releases to be available independent from each other and independent from the latest changes on the main development branch, while on the other hand the IDE’s (e.g. Arduino and PlatformIO) must also be able to recognize when there is a new version so there should be one stable URL that always points to the latest stable release.

A possible solution might be to create one separate branch for releases and update this branch only when a new release becomes available. The head of that branch will then always point to the latest stable release. (But I’m not aware of the best practices for how to best implement this on GitHub.)

The recent problem with the library was that there had been made substantial changes to the library but the version number was not updated so PlatformIO did not get the changes. From interface perspective there maybe were no impacting changes, but there were substantial changes in the code and in the examples. This was very noticeable because the new ttn-abp.ino and ttn-otaa.ino examples were not showing up via PlatformIO. (This issue has been addressed by the recent update of the version.)

Additional ideas and suggestions:
Changing the name of the library is also a good moment for updating the versioning scheme and switch to true semantic versioning. Why not change the version to 1.6.0(.0) Now? It does not matter that there have not been stellar code changes but still increase the minor version because it will benefit the versioning of any new versions of the library to come. (After any revamping of the library you can just continue with the ‘new’ versioning, the version of the current library does not have to wait for that.)

It would be handy when the library name and the repo name are the same. Maybe it is an option to ‘fork’ (or similar) repo arduino-lmic to lmic-arduino and continue from there (leaving the old repo url exist to prevent breaking existing references in IDE’s).
(I noticed that the library name has not yet been updated in README.md.)

Note:
PlatformIO’s crawler will need some time to notice any changes like the library name change. Last time it took a day before I saw the version change on PlatformIO.
Like mentioned earlier, PlatformIO will only notice changes when the version has changed, that may hold for changing the library name as well (not noticing the change because the version has not changed).
I’m not sure how PlatformIO will handle library name changes, especially when the location (URL) where it found the source has not changed.

Thanks again for your efforts.


#18

The PlatformIO crawler has successfully picked up the LMIC-Arduino library (formerly IBM LMIC framework) name change.