Make Boards/Library Manager more helpful regarding version numbers

[per1234]

Describe the request

Pre-release update notifications

By default, don't provide update notifications for pre-release versions when the user has a stable release version installed.

An option should be provided to enable these notifications. This should be accessible only via the advanced settings, since pre-releases are intended for advanced users.

Select stable version by default

The version menu in the "Library Manager" and "Boards Manager" views should default to having the newest non-pre-release version selected, if any are available.

Communicate implications of significant version installation or updates

When the user does an installation of an unstable version, display a confirmation dialog that explains the implications:

Warning: The library version 1.2.3-rc1 you have chosen to install indicates a pre-release version, which is intended only for beta testing.

Warning: The library version 0.1.2 you have chosen to install indicates the library is still undergoing initial development.

When the user does an update resulting in a major version bump, display a confirmation dialog that explains the implications:

Warning: The library version 2.0.0 you have chosen to update to is a major version increment from the previously installed version. This indicates there have been breaking changes to the API.

Describe the current behavior

The most efficient and user friendly way for an Arduino library or boards platform maintainer to distribute their project to users is via the Arduino Library Manager and Boards Manager systems.

This system might be used for distribution at any phase of the project development. These phases are communicated in a machine readable format via the version number, according to semver:

• Pre-release (MAJOR.MINOR.PATCH-PRERELEASE)
• Beta (0.MINOR.PATCH)
• Major version increment (indicates breaking API change)

Arduino IDE offers installation or updates of these libraries and boards platforms to the user in two ways:

• The "Library Manager" and "Boards Manager" views.
• Update notifications shown on startup (#177, #1188 Implemented filter and update all for libs/boards #1361)

Arduino IDE does not make any distinction between the development phases indicated by the library and platform release version numbers. The highest version is always offered for installation and update by default.

🙁 Users are prompted to install versions that are unstable or cause breaking changes.
🙁 Maintainers are unable to take advantage of the system for distributing their project to beta testers.

Arduino IDE version

2.0.0

Operating system

All

Operating system version

Any

Additional context

Additional requests

• Make Boards/Library Manager more helpful regarding version numbers #683 (comment)
• Make Boards/Library Manager more helpful regarding version numbers #683 (comment)

Related

• IDE wants to update to Version 6 beta  bblanchon/ArduinoJson#787
• Stop pushing non-GA versions onto the release channel esp8266/Arduino#5554
• https://forum.pjrc.com/threads/53548-Arduino-CLI-And-IDE-now-Released-Teensy-Supported!?p=312795#post_312795

Issue checklist

• I searched for previous requests in the issue tracker
• I verified the feature was still missing when using the latest nightly build
• My request contains all necessary details

[marcelstoer]

By default, don't provide update notifications for pre-release versions.

Something like this is definitely needed.

[devyte]

I think this would be very helpful. New users are prone to not consider the implications of moving to a new version with enough care, despite warnings and explanations in the docs. A last warning integrated into the IDE itself would make sure everyone is made aware.

[KurtE]

Thanks @per1234,

Yes this would be very useful for working with the Teensy boards, where we typically do several beta releases as a way to allow those of us who are working on features to have a common code base to continue work with. But the typical user who only wishes to only work with stable stuff should not, necessarily see when a new beta release comes out, and worse off, have them automatically updated to the beta, when the notification comes up at program startup saying one or or boards are out of date, and you are given a default option to update all.

Different variations of this issue keep coming up on forum threads like, just now:
https://forum.pjrc.com/threads/71370-Teensy4-1-reading-from-Serial-Monitor-of-Arduino-IDE?p=315178&viewfull=1#post315178

And I commented about it up on the Arduino forum thread:
https://forum.arduino.cc/t/invalid-fqbn-not-an-fqbn/1046630/5

[PaulStoffregen]

@per1234 - 7 weeks ago you asked me to comment. Sorry for the slow response. I've been bogged down by supply chain challenges which are still largely unresolved. I'm taking time today to write a reply, because this truly is important ongoing development of the Arduino ecosystem.

Software releases can be grouped into broad categories. Here are the four I'd recommend. Usually we think of these in terms of the software's expected quality, and indeed that matters. But I believe the much more important aspect of these categories is the desired level of feedback or expected style of contribution by people who install and use them.

1. Experimental or Alpha - feedback or contribution regarding the overall design is appropriate
2. Beta Test - major design decisions have been made but not fully finalized, focus is features and pragmatic testing
3. Release Candidate - design and features are fixed, bug fixes only
4. Stable Release - final version meant for general use, feedback usually directed for future versions

All 4 of these can be superseded. So perhaps from a IDE or CLI tool design that would be 8 distinct categories. Or maybe that's 4 categories and a boolean flag whether it has been superseded by another version, either in the same category or another "more stable" category.

The package index for boards and properties file for libraries should be extended to allow authors to provide version-specific metadata. More on that in a moment....

A first major issue is deciding and implementing how Arduino would parse semantic version numbers into these 4 (and any similar set) categorizes and exactly how the latest vs superseded decision is made. Maybe this semver-to-category mapping and the details of when a version is considered superseded should be documented in the platform index spec.

Obviously the IDE should not show notifications for anything superseded.

How the IDE notifies people of new versions should be tailored to each category. The language matters. The message should clearly but concisely explain the expected quality and appropriate type of feedback or contribution to the software development (hopefully more eloquent than the 4 above, but same general idea).

If metadata is available to explain what this version offers, it should be shown (perhaps in abbreviated form with a UI element to expand) in the notification. Today the notifications offer no information other than the version number. Long-term, all Arduino users will enjoy a better overall user experience if software is usually published with metadata to help users make these choices.

User choices are excellent opportunities to learn about the user's preferences. The IDE should seek to learn as much as (reasonably) possible from the user's choice, both their general attitude and their level of interest in each individual board and library. The notification should ask a question along with the choice whether to install the new software. The question should be tailored to the category, and the default set based on any prior learning of the user's preferences. For example, when offering an Experimental category update, don't install choices might be "never recommend experimental software", "no interested in this board/library development", "not now but tell me when the next version comes", etc. Likewise, when a new stable version is offered, choices might be "yes, give me the latest", "no, I want this version, but tell me of fixes", "no, don't upgrade anything".

When users click the drop-down menu in the Boards Manager to install a specific older stable version, or to install one of the other categories, that too is highly valuable information about the user's preference. Every opportunity to learn which category or range of categories the user prefers for each platform and each library should be captured somehow. Each time the user compiles and uploads is also an indicator of preference for the category installed at that moment. This information should also "age". If someone installs an experiment version, tries just a few uploads, then goes back to stable and remains there for hundreds of uploads, their brief flirtation with an experimental version should be gradually forgotten.

How frequently users are shown new version notifications should strike a balance between respecting their prior explicit choices, offering updates which supersede what they have installed, guidance from what is known of their preferences, and avoiding remaining too stagnant by never notifying. The more a user has clearly made an explicit choice, the longer the interval should be between notifications which again question their original decision. Again, the IDE should learn as much as possible from every user choice, as to their level of interest in the 4 categories, for each board and library. If a user is known to have interest, show notifications. But it a user it known to not be interested, allow a very long time before pestering them with a reminder.

Earlier I mentioned version specific metadata. Showing even some info about what each version offers, both in the Boards Manager when selecting the drop-down list (maybe a hovering / floating window like the code completion) and in the notifications is important, as users have no easy way to see what each version number really means. There are probably many difficult challenges, especially for libraries where a properties file applies to only the most recent version. Especially for superseded versions, metadata which explains what is fixed between 2 versions is ideally what's needed. Whether library authors and boards maintainers would create such specific update-from-version-X descriptions is a good question, but that is exactly the sort of info users need most when faced with the decision whether to install. Hopefully future IDEs can make that possible.

Whew, that turned out really long and maybe a bit too philosophical. But you did ask me to comment. Hopefully even 7 weeks late, maybe some concepts worth considering for future Arduino IDEs?

[PaulStoffregen]

FWIW, for Teensy I've started publishing the non-release versions with major number 0, as that seems to be the least-bad way available today for a single platform index.

So today Teensy's package index has:

1.57.1 -- latest stable
1.57.0
1.56.1
0.58.2 -- latest beta

It's less than ideal for people wishing to use the very latest beta, since IDE 2.0.1 prompts them (too aggressively) to upgrade to 1.57.1.