Attempting to install an incompatible add-on presents a dialog that can be confusing to some users

XLTechie commented 2 years ago

Steps to reproduce:

While running an NVDA alpha or beta in the 2022.1 series:
Attempt to install an add-on which is not currently compatible with that version of NVDA. This was first noticed in relation to the ClipSpeak add-on, in this discussion on the nvda-addons mailing list, and caused much confusion there. At the time of this writing, it can also be found with other incompatible add-ons, such as: Quick Note Taker, or my own discontinued Debug Helper.
NVDA presents a dialog to indicate that the add-on can't be installed because it is incompatible.

Actual behavior:

The add-on, for the case of Clipspeak, has a compatible range of 2018.3.0-2019.3.0. As expected, it won't install in a 2022.1 NVDA alpha.

However the dialog which NVDA shows is as follows:

Add-on not compatible
dialog
Installation of Clipspeak 1.1 has been blocked. An updated version of this
add-on is required, the minimum add-on API supported by this version of
NVDA is 2022.1

In the topic linked above, this wording confused a very experienced, and very technical user. Even after I had figured out what was going on in that case, I still misunderstood what this wording meant upon first reading, and thought it was incorrect.

Expected behavior:

The wording is technically true. However it expects the user to have ready knowledge about the way NVDA manages compatibility, in order to understand what it is saying.

For the case of add-ons which are no longer compatible with the currently installed version of NVDA, I would expect a more end-user friendly dialog to say something like the following:

Add-on not compatible
dialog
Installation of this add-on has been blocked.
Clipspeak version 1.1 is only compatible with versions of NVDA through 2019.3.0.
This version of NVDA is too new to support this add-on.
An updated version of Clipspeak is required.

In short: end-users do not care about internal API versions. They care about whether an add-on works with their current version of NVDA.

System configuration

NVDA installed/portable/running from source:

Source.

NVDA version:

A 2022.1 alpha series build.

Windows version:

N/A

Name and version of other software in use when reproducing the issue:

Other information about your system:

Other questions

Does the issue still occur after restarting your computer?

N/A

Have you tried any other versions of NVDA? If so, please report their behaviors.

No.

If NVDA add-ons are disabled, is your problem still occurring?

Not tested.

Does the issue still occur after you run the COM Registration Fixing Tool in NVDA's tools menu?

Yes

XLTechie commented 2 years ago

CC @michaelDCurran @Qchristensen @britechguy

britechguy commented 2 years ago

A big, SECONDED, as to the opinion expressed in this issue.

Error messages are not for developers, but users, and this one as currently presented, is entirely misleading to the typical end user of NVDA (and I include myself there). Absent some really esoteric knowledge, what it says is just plain wrong to the average reader, and we want "the average reader" to take appropriate actions, when possible, based upon what error messages tell them.

josephsl commented 2 years ago

Actualy, CC @feerrenrut , @derekriemer , @nvdaes and other add-ons community members

Note that UI string changes are not accepted for 2022.1, but I think we might as well take care of this in 2022.2. I advise a careful consideration of the messaging here because:

As Luke and Brian point out, the current messaging does not say the latest compatible NVDA version for an add-on.
Further, the messaging implies people know about the backward compatibility policy, something newbiews are not even aware of unless told otherwise.
This message will be translated into many languages, so let us make it concise while providing needed information.

In addition to the proposed message, others can include (addonName is the name of the add-on being installed):

addonName is incompatible with the version of NVDA you are using. Last tested version: lastTestedVersion, add-on must be compatible with currentNVDAVersion.
addonMame is incompatible. The last tested NVDA version (lastTestedVersion) is older than currentNVDAVersion.
Anything that's concise, easy to translate, and communicates the reason clearly.

I remember the add-ons community going through a massive confusion in early 2019 when version compatibility flags were first introduced. I wish we were alerted to the messaging problem earlier, but at least I'm glad that we have a record of this for posterity.

Thanks.

CyrilleB79 commented 2 years ago

I agree that speaking of API is not user-friendly at all and should be changed.

Some points to keep in mind however:

Maybe two messages should be created:
- one for NVDA version < min required version, i.e. when the add-on is too new with respect to NVDA
- one for NVDA back compa version > last tested version, i.e. when the add-on is too old with respect to NVDA
The issue with last tested version is that the message remains unclear: E.g: Current NVDA version = 2022.1, last tested version of the add-on = 2021.1, but the message does not indicate clearly that you can use this add-on with NVDA 2021.3.5

Brian1Gaff commented 2 years ago

This is what comes from having testers who are not new enough users to see the wood for the trees so to speak. Its a bit like when I read some of the messages generated by the build engine talking about various sorts of errors like linting which mean zilch to me.

feerrenrut commented 2 years ago

The NVDA log should indicate clearly to the developer how the version check failed.

When initially developing this we struggled to find the right balance between enough information to understand that this is a "version mismatch" problem without overwhelming a user, and a hint to core or addon developers about the versions required.

This work was done in PR #9151 based on write up in issue #9055

Note that there are already two messages (See: addonGui.py line 610 snippet included below.)


def _showAddonRequiresNVDAUpdateDialog(parent, bundle):
    incompatibleMessage = _(
        # Translators: The message displayed when installing an add-on package is prohibited,
        # because it requires a later version of NVDA than is currently installed.
        "Installation of {summary} {version} has been blocked. The minimum NVDA version required for "
        "this add-on is {minimumNVDAVersion}, your current NVDA version is {NVDAVersion}"

def _showAddonTooOldDialog(parent, bundle):
    confirmInstallMessage = _(
        # Translators: A message informing the user that this addon can not be installed
        # because it is not compatible.
        "Installation of {summary} {version} has been blocked."
        " An updated version of this add-on is required,"
        " the minimum add-on API supported by this version of NVDA is {backCompatToAPIVersion}"

We COULD avoid mentioning the add-on API version, however it would be easy to mislead the message receiver. Be aware that the API version and NVDA's version are two distinct concepts.

britechguy commented 2 years ago

You know, this is such a simple thing to fix, and that includes if you want different messages to a developer error log versus what's front facing to the user.

And it's also simple, very simple, that what the end user should be told is that, "This add-on is combatible starting with NVDA version {lower limit} through version {higher limit}. You need the add-on compatible with {insert running NVDA version }."

This is not rocket science. It is possible to give a clear, concise, and exact message that any end user can easily understand.

They don't care that something's been tested with something else. They don't care about what's necessary for development teams to do in terms of fixing a problem. When they get error messages, they want to know what's incorrect about the current situation and, ideally, what they need to seek out to remedy it.

josephsl commented 2 years ago

Hi, one important thing to keep in mind: a given API release is valid through a year.x release. For instance, if someone installs an add-on with last tested version set to2022.1 in NVDA 2022.2 or 2022.3, folks may get an impression that one needs to either downgrade to 2022.1 or obtain a newer add-on release compatible with a newer NVDA version. The fix I always deploy for my add-ons is to update the last tested version whenever beta 1 of the said version is released, something that could be seen as a “luxury” by some – that is, not everyone has the time to update the manifest (made a bit more complex as we know that users do edit manifests from time to time, something that’s not ideal but seen as necessary as a last resort option). Thanks.

feerrenrut commented 2 years ago

You know, this is such a simple thing to fix, and that includes if you want different messages to a developer error log versus what's front facing to the user.

Please go ahead and create a PR @britechguy

XLTechie commented 2 years ago

@feerrenrut I'll be happy to be assigned on this one. I was planning to do a PR anyway, once some feedback came in.

britechguy commented 2 years ago

@feerrenrut

I am not an NVDA developer, nor do I intend to become one. I do, however, have over a decade of experience as a programmer analyst and still do limited coding.

Just because someone can identify what is, in fact, a simple fix from a complex one doesn't mean they're voluntering to do it, nor should be expected to do it.

Writing clear error messages is not complex. Writing split messages for logging in addition to front-facing to users is not complex coding, either. That still doesn't mean that it's my responsibility to do it.

feerrenrut commented 2 years ago

@britechguy The condescending tone isn't very helpful, I'd like to request you reconsider that. You of course are free to offer as little or as much help as you wish.

@XLTechie if you are interested in taking this on. Please go ahead. I'd recommend trying to get people to agree on the messages first. You can do that via PR or this issue, I don't mind.

britechguy commented 2 years ago

@feerrenrut : I strongly suggest you consider that your prior comment could be read as dripping with snark.

I have been around these parts, and you have been involved in a number of issues I've commented on or started, to know darned well that I am not a Python developer nor have any interest in being an NVDA developer. I'm am a user with a particular background.

What you wrote reads as heavy snark, at least to me.

Turnabout is fair play.

XLTechie commented 2 years ago

I have created a pull request to address this issue (#13673).

Some notes:

Regarding @josephsl's suggested wordings: I prefer to avoid anything talking about "last tested version", because that is still in the realm of API version. A user is only slightly more likely to know what last tested version means to them, than they are to know what API version means to them.

Below I have provided examples of the dialogs created by the PR. Feel free to suggest alternatives here, as @feerrenrut mentioned above.

Testing:

For anyone who wants to test my proposal for how to resolve this, please download this try-build.

Here are two add-ons you can use to demonstrate: one that is too old, and one that is too new.

Sample of revised add-on is too old for NVDA dialog:

Installation of this add-on has been blocked. Add-on Name version #.# is too
old to work with your version of NVDA.
The add-on is only compatible through the 2021 NVDA series. Please
download a newer version, or contact the add-on's author: Firstname Lastname
<email>, to ask for an update.

Sample of revised add-on is too new for NVDA dialog:

Installation of this add-on has been blocked. Your version of NVDA (2022.2)
is too old to support Add-on Name version #.#.
Please update NVDA to at least version 2025.1, to use this version of
Add-on Name.

feerrenrut commented 2 years ago

Thanks for the write up @XLTechie, this looks to going in the right direction. Some feedback:

through the 2021 NVDA series

This alludes to a concept that doesn't exist elsewhere, EG that all the 2021 releases are somewhat related. The fact that API breaking changes are planned for a 20XY.1 release is only due to current process. There may be another wording that works for this, but I'd like to question why try to include this at all? Is the goal let the user know which NVDA version they can downgrade to, so they can continue to use this version of the addon? This (downgrading) isn't something NV Access wants to recommend to users.

The second suggestion seems fine.

XLTechie commented 2 years ago

through the 2021 NVDA series

This alludes to a concept that doesn't exist elsewhere, EG that all the 2021 releases are somewhat related. The fact that API breaking changes are planned for a 20XY.1 release is only due to current process.

I know, I didn't like it either. It was the best of everything I could think of, without, as I said in the PR, carrying a compatibility map in core. Note that such a map would not only need to cover situations going forward, but would need to be extended back to some reasonable degree, perhaps 2019.3.1. I don't like that idea either, though if it becomes the preferred (or only) solution, it isn't difficult to do. I just didn't want to do the data mining, unless it was (1) the only way, and (2) likely to be adopted.

There may be another wording that works for this, but I'd like to question why try to include this at all? Is the goal let the user know which NVDA version they can downgrade to, so they can continue to use this version of the addon? This (downgrading) isn't something NV Access wants to recommend to users.

That wasn't my first (or even second) thought as to why to give this information, although see point 3 below for why it does have some merit IMHO.

Informational. We are doing nothing other than exposing the manifest in a user friendly way, so that the user knows what's what. You mentioned while closing one of my issues, "empowering users". Well, giving them information in a way they can easily digest it, no matter their level of expertise, does that. We are telling them that this add-on will not work in the current circumstances. It will always be easier, if it exists, to upgrade the add-on, rather than to downgrade NVDA. But if you really need to downgrade, you will need to be in this version number neighborhood to do it. We have that information, approximately, keeping it hard to reach just because we can, seems somehow wrong.

In that view, we are providing what the user needs to take an informed decision, not promoting a particular decision.

Understanding timing. The second element of the above, is what power that information gives you. Sure it gives you what you need to know to downgrade, but to me that isn't the point. What it really gives the user the power to understand, is how long they should wait.
- Consider that 2022.1 has been released, and the user installs it, followed by a new add-on they need. Only the installation is blocked, with the reason that this version of the add-on only worked in the 2021.X series (or however it's worded). Now the user knows that the add-on worked on the immediately previous version of NVDA. It is not unreasonable to think that a user with that knowledge, may decide to wait a few weeks for the add-on to catch up with NVDA.
- Alternatively, if it says that this add-on last worked with 2019.2, the user now has a very good idea that no update will be forthcoming, and can start searching for some other way to use their required app.
Promoting NVDA as much as possible. Some users rely on certain add-ons for their work, etc., and when those add-ons aren't upgraded, they can't upgrade either. Or if they find out they need them, they must downgrade to gain compatibility. Regardless of whether NV Access likes it when people downgrade, isn't it better to show them how far they need to downgrade, so that they might easily do so, rather than saying, effectively: sorry, this add-on doesn't work in this version of NVDA, and we aren't going to tell you when it might have even though we know (approximately).

Those of us who work with end users on a regular basis, are very familiar with the "if the add-on doesn't work with NVDA any more, I'll just go back to Jaws, because I need (insert app name)." solution. At least providing an easily available "downgrade target", has the potential to divert that thinking.

I recognize this as the weakest answer, and at best a subsidiary reason to the first. Still, I think it is at least partly behind why most other open source projects (I was downloading LibreOffice yesterday) make their older versions prominently available and downloadable. Even if the user has to go back, they stay in the ecosystem, and aren't made to feel like their doing something wrong. If you need an older version for some reason: hey we don't support it, but we want you to use our product, even an older version, so here it is.

It was already providing API version, leaving me to think that NV Access preferred that it provide some kind of actionable information. Therefore I tried to provide a better kind of actionable information.

feerrenrut commented 2 years ago

Ok, I agree with that.

The in-development add-on store, will eventually be able to provide this. I say eventually because it is not a core goal, however it won't be difficult information to provide. Additionally, it will make it possible to implement a way for users to check which of their add-ons have compatible versions before they upgrade NVDA.

I'd suggest taking the simpler approach now, and adapting this with better information from the add-on store when it is available. Suggestions:

Continue to use the "minimum NVDA API version" from the add-on manifest.
Perhaps instead specify the range: "This add-on version can only be used with NVDA versions in the range {minimumNVDAVersion}-{lastTestedNVDAVersion}"

Brian1Gaff commented 2 years ago

Some software seems a bit kinder in that the friendly warning appears and a button saying something like details is there for those needing to know the dirty truth! In microsofts case these details are usually so incomprehensible as to be pointless. Brian

@. Sent via blueyonder. Please address personal E-mail to:- @., putting 'Brian Gaff' in the display name field. Newsgroup monitored: alt.comp.blind-users ----- Original Message ----- From: "Luke Davis" @.> To: "nvaccess/nvda" @.> Cc: "Subscribed" @.***> Sent: Monday, April 25, 2022 6:25 AM Subject: Re: [nvaccess/nvda] Attempting to install an incompatible add-on presents a dialog that can be confusing to some users (Issue #13632)

CC @michaelDCurran @Qchristensen @britechguy

-- Reply to this email directly or view it on GitHub: https://github.com/nvaccess/nvda/issues/13632#issuecomment-1108092251 You are receiving this because you are subscribed to this thread.

Message ID: @.***>

XLTechie commented 2 years ago

Continue to use the "minimum NVDA API version" from the add-on manifest.

In the case of add-on too old for NVDA, I.E. where the "series" message was used, it would be lastTested, not minimum, if I understand you correctly. Which brings us to:

Perhaps instead specify the range: "This add-on version can only be used with NVDA versions in the range {minimumNVDAVersion}-{lastTestedNVDAVersion}"

And of course the problem with last tested, is that it can be inaccurate by several major versions, if no API breaking change happens. I.E. most add-ons will say last tested 2021.1, but will still work with 2021.3.5 or whatever. Therein lies the problem.

Thinking about this further, if we believe the store will eventually remove this problem, then the maintenance burden for a compatibility map wouldn't really be that high, because we could discontinue it once the store came into play.

feerrenrut commented 2 years ago

@XLTechie

And of course the problem with last tested, is that it can be inaccurate by several major versions, if no API breaking change happens. I.E. most add-ons will say last tested 2021.1, but will still work with 2021.3.5 or whatever. Therein lies the problem.

This value is intended to be the author's guarantee that given a changed addon API version, they have tested the addon with those changes. Naming is hard, and I accept this name lastTestedNVDAVersion does not encapsulate all of that.

The confusion comes from equating an NVDA version to an add-on API version. However, when there are no backwards incompatible changes, from the perspective of a released add-on the API is equal. Even with additions to the API, logically these are irrelevant to an addon released before their introduction.

The compatibility check is looking for two overlapping windows of compatibility. One range is formed by NVDA Addon API current version, and the backwards compatible to version. The other range is formed by the addon minimum required NVDA addon API version and last tested NVDA Addon API version. If there is no overlap in these ranges, then further investigation by the add-on author is required to confirm.

XLTechie commented 1 year ago

@britechguy, @josephsl, @CyrilleB79, can this be closed given the following?

Under the add-on store (i.e. as of NVDA 2023.2), the problematic dialogs have changed.

Attempting to install an add-on that is out of date

If an add-on is too old to work in 2023.2, the dialog's wording has changed to:

Add-on not compatible  dialog

Warning: add-on is incompatible: Add-on Name N.N. Check for an updated
version of this add-on if possible. The last tested NVDA version for this
add-on is 2021.1, your current NVDA version is 2023.2. Installation may
cause unstable behavior in NVDA. Proceed with installation anyway? 
About add-on...  button  Alt+  a
OK  button
Cancel  button

Attempting to install an add-on newer than NVDA

If you attempt to install an add-on with a minimum NVDA version higher than the currently running copy, the dialog contains the following:

Add-on not compatible  dialog

Installation of Add-on Name N.N has been blocked. The minimum NVDA
version required for this add-on is 2024.1, your current NVDA version is
2023.2
About add-on...  button  Alt+  a
OK  button

CyrilleB79 commented 1 year ago

Seems OK to me.

seanbudd commented 1 year ago

Closing as resolved by #13985

nvaccess / nvda