search

pschatzmann / arduino-audio-tools

Arduino Audio Tools (a powerful Audio library not only for Arduino)
GNU General Public License v3.0
1.42k stars 222 forks source link

library.properties needs to get updated before tagging #1642

Closed egnor closed 1 month ago

egnor commented 1 month ago

Problem Description

In the v0.9.8 version of the repo, library.properties still says 0.9.6: https://github.com/pschatzmann/arduino-audio-tools/blob/e6172e2839c0d322f9b1f4076dd6295004facd53/library.properties#L2

It's updated at HEAD, but, the Arduino library indexer wants library.properties to update in each tagged version, otherwise it doesn't know the right version number and skips it:

2024/08/02 19:37:58 Checking out tag: v0.9.8
2024/08/02 19:37:59 Release audio-tools:0.9.6 already loaded, skipping
2024/08/02 19:37:59 Arduino Lint has suggestions for possible improvements:
Click to expand Arduino Lint report

(By the way, this applies to many of the other associated libraries as well. Not sure if there are stock release scripts associated with all of them that could get updated.) Obviously I can check out the library myself from github, but that's fussy and doesn't work well with hermetic reproducible builds.

Device Description

Any

Sketch

N/A

Other Steps to Reproduce

No response

What is your development environment

Particularly applicable to the Arduino IDE or arduino-cli, as those use the Arduino library registry by default. (Platformio has its own registry, and I'm less sure of the semantics there.)

I have checked existing issues, discussions and online documentation

pschatzmann commented 1 month ago

This library is not published via the Arduino library manager!

Apart from this, if you double check in the main branch, this has already been corrected

egnor commented 1 month ago

Apart from this, if you double check in the main branch, this has already been corrected

And if you double check my original report, I noted that it is updated at HEAD, but since the latest tagged-in-git version (v0.9.8) still has an old version (0.9.6) in library.properties, that doesn't work for indexers.

Of course the old tagged version shouldn't be changed. What's important is that when 0.9.9 is released, the library.properties file is updated. I was hoping maybe there was some release script or workflow that could get updated to make sure this happens, since it seems to be missed a lot.

This should also get fixed for libraries like libhelix, whose library.properties is still at 0.1 even though its current version is 0.8.4 (!). I can go file a bug in that repo, or suggest workflow changes, or whatever would work best for you to resolve this mismatch.

This library is not published via the Arduino library manager!

Ah but this library is in fact referenced in the Arduino library registry. I know this because I added it. I was hoping that this glitch could get fixed for future releases, so the indexer to keep up with versions you release, with no extra work on your part. (Even for people who manually stuff a git checkout into their libraries/ directory, keeping library.properties updated will ensure the metadata is correct, which makes support easier.)

There's nothing wrong with stuffing a git checkout in libraries/, but it's not great for anything where development is shared, or where repeatable builds are desired.

egnor commented 1 month ago

(Admittedly, since it's Very Very Unusual for an otherwise very well maintained Arduino-targeted library to not be listed in Arduino and platformio registries, I figured you probably had some sort of philosophical objection to these registries, but I couldn't find any such objection noted, so figured I would go ahead and add it. On platformio you can use direct git references, but the Arduino tools don't offer that.)

pschatzmann commented 1 month ago

It was a conscious decision by me not to add my libraries to the Arduino Library manager in order not to attract too many beginners.

It is already very annoying that I have to answer the same questions over and over again just because too many people are too lazy to read the available documentation.

So I am asking you to remove them from the registry again or you will need to help me by answering the discussions and issues.

pschatzmann commented 1 month ago

See also here

egnor commented 1 month ago

I propose adding a note like this at the top of README.md:

[!CAUTION] DO NOT EXPECT SUPPORT FOR THIS LIBRARY

We love all our users, BUT we lack the capacity to answer questions and debug problems. If it doesn't work, you will need to self-rescue.

In general this library is NOT RECOMMENDED for people less experienced with C++ embedded development; friendlier choices include Teensy Audio (for the Teensy), Seeed Audio (for SAMD21/SAMD51), or ESP8266Audio (for ESP8266 and ESP32).

If you do use this library after all that, please set your expectations accordingly and MAKE SURE TO READ THE DOCUMENTATION BELOW.

I would add something similar in the issue reporting template, and anywhere else uninformed questions are coming in. With all that in place (and I'm happy to send PRs), I'd be happy to help with issue triage!