Closed Bug 1752706 Opened 3 years ago Closed 3 years ago

Summarize (document) state and history of "Thunderbird Extension APIs" for developers, to minimize overal confusion?

Categories

(Thunderbird :: Add-Ons: Extensions API, enhancement)

Product:
Thunderbird
Component:
Add-Ons: Extensions API
Type:
enhancement

Tracking

(Not tracked)

Status:
RESOLVED WORKSFORME

People

(Reporter: bugzilla.mozilla.org, Unassigned)

Details

User Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36

Steps to reproduce:

There's significant confusion in some part of the smarter-user + developer community surrouding Thunderbird add-ons/extensions, their APIs, and how it relates to the "jolt" a user gets when they're asked by an add-on to "allow permissions to do anything." Examples:

https://github.com/lkosson/full-address-column/issues/11#issuecomment-1024851862
https://www.reddit.com/r/Thunderbird/comments/sevrmw/how_to_display_only_email_addresses_in/hunf9oe/?utm_source=reddit&utm_medium=web2x&context=3
https://addons.thunderbird.net/en-US/thunderbird/addon/full-address-column/

Actual results:

Unncessary confusion from users and developers.

Expected results:

Why not writeup a few sentences/paragraphs and list a few references, similarly to the way the following article does for user-side perspective for "requested permissions"?

https://support.mozilla.org/en-US/kb/permission-request-messages-thunderbird-extensions

The possibly post this article (minimally) at the top of the the following Bugzilla area?

https://bugzilla.mozilla.org/buglist.cgi?product=Thunderbird&component=Add-Ons%3A%20Extensions%20API&resolution=---&list_id=15976970

Summary: Summarize (document) state of "Thunderbird Extension APIs" for developers, to minimize overal confusion? → Summarize (document) state and history of "Thunderbird Extension APIs" for developers, to minimize overal confusion?

Since I'm unable to edit (I guess?) my above comment, I'd like to stress:

This request for docs is targeted primarily for add-on/extension developers, and less for users. Possibly said docs can also assist development-savvy "power" users, but it is not targeted for general users (like https://support.mozilla.org/en-US/kb/permission-request-messages-thunderbird-extensions is), but it might be worth making a reference in the excellent article list that presented in the aforementioned (in the parenthetical) article.

We have a full in-depth WebExtension documentation for developers:
https://developer.thunderbird.net/add-ons/mailextensions

Is there anything where that documentation falls short?

On the same page, there is also a section giving an overview about the different add-on types:
https://developer.thunderbird.net/add-ons/about-add-ons

For users, we have linked the page you referred to right from the product, from the add-on permission request popup. The user has to click it on its own :-)

[Dislcaimer: I do not have sufficient time to write this note concisely. Apologies]

Summary with an analogy: I want someone to describe to me the pattern of a specific leaf in a few sentences. https://developer.thunderbird.net/add-ons/mailextensions (an absolutely beautifully structed set of docs) is giving me a 500-page book about a forest. It's not quickly solving the main request.

Here's a completely-different analogy with more-detailed perspective:

  • Electrician installs a light switch in my house.
  • Electrician must add a disclaimer as a label on the switch cover: "You could die of electrocution if you use this switch."
  • I ask the electrician: "what the heck, how can you install a light switch that could kill me?"
  • Electrician says: "I didn't, I'm just required to do that because the electrical infrastructure does not prevent users from getting electrocuted if a dumb electrician installs a light switch. So I'm legally bound to put that label on the switch."
  • I say "that seems dumb."
  • Electrician: "I agree. But there's nothing I can do about it. It's basically a fact of life as a light-switch user now."

This is what I'm observing how there's general ignorance in the Thunberbird community about extension permissions. There's presumably LOTS of users freaking out when a permission "must be granted access to do anything on your computer." And then the power user and devleper (this actually happened; see references in my first comment above) replies to users that are freaking out about this: "there's nothing we can do, our hands are tied by Thunderbird-infrastucture limitations."

When in fact, there's more to the story. Here's a comment that clarified things for me:
https://github.com/lkosson/full-address-column/issues/11#issuecomment-1024954835

Now John Bieling might be saying: well yeah, that's all documented in our docs:
https://developer.thunderbird.net/add-ons/mailextensions

My retort: there's absolutely no way I can glean the precise point at from the above mailextensions docs without spending LOTS of time (that I won't spend, frankly) digesting all the details and deriving my own summary similar to:
https://github.com/lkosson/full-address-column/issues/11#issuecomment-1024954835

So in order to best enable all the develpers and power users to best educate the "users that freak out about the gnarly permissions request," I suggest givine them (the developers and power users) a brief description of the legacy and issues of how we've arrived here and what can potentially be done in the future.

Now, if https://github.com/lkosson/full-address-column/issues/11#issuecomment-1024954835
is incorrect, for me that only bolsters the argument make a brief blurb to describe this problem. And before anyone thinks of blasting lkosson that they don't understand something, consider that he seems to me like a reasonably-thorough and thoughtful developer. I don't run across the very often.

But the point is: the problem we're battling here is ignorance without a easy (read: short document) way to remove this ignorance.

Or... maybe I simply do not understand -anything- that's going on here. This might be the case, given that I'm just another power user that was only introduced to all this Thunderbird-extension-permission stuff yesterday. Literally. So yes, I'm terribly igonorant. What I do not understand: why this igorance seems to be rapament in the general community. It doesn't seem like it has to be. My proposal is attempting to be one step in helping.

(In reply to John Bieling (:TbSync) from comment #2)

We have a full in-depth WebExtension documentation for developers:
https://developer.thunderbird.net/add-ons/mailextensions

Is there anything where that documentation falls short?

On the same page, there is also a section giving an overview about the different add-on types:
https://developer.thunderbird.net/add-ons/about-add-ons

For users, we have linked the page you referred to right from the product, from the add-on permission request popup. The user has to click it on its own :-)

https://github.com/lkosson/full-address-column/issues/11#issuecomment-1024954835 is correctly stating the permission system and how extensions which need more than the available WebExtension APIs can request the legacy unrestricted access and do everything like they could in TB68 an earlier (without telling the add-on users back then).

For users, we have the link to https://support.mozilla.org/en-US/kb/permission-request-messages-thunderbird-extensions right in the permission request popup. What information for users is missing in that document? It states that the add-on is requesting that permission, because none of the standard WebExt APIs is doing what is needed. It states that those add-ons are subject to human review. Add-on developers can redirect users to that document, to educate their users.

I did not get your analogy with the light switch.

Users do not need to read the dev docs, the support article should be sufficient for them.

Regarding developers, I think they are well aware of the permission system. Or are you suggesting, that a vast majority of them does not know about the Experiment permission? They did include an Experiment, so they must have read some part of the documentation. Do you want me to add a highlighted "causion" box here:

https://developer.thunderbird.net/add-ons/mailextensions#experiment-apis

which states that the permission will be prompted?

We're going in circles here, I'm sorry to say. I appreciate the diligence, nonetheless.

John writes:
"Users do not need to read the dev docs, the support article should be sufficient for them."

This is NOT for the users, directly. It's for the developers. (So they can quickly understand the overall dynamic in a summarized, and not convey "essentially untrue" things to the users. Basically: write a blurb similar to lksonn's in a public place, get it approved by this project--whatever that means--and then release it in the docs tree and add the weblink here.)

Alas, John, I doubt you're going to get what problem I'm trying to solve and how. This is not my claiming your bad or wrong in any way. Maybe I just don't understand what's happening, maybe I'm not listening to you well enough. However, my claim is: you might be having difficulting seeing one tree in the midst of the details of the forest.

If we could get on the phone I'm sure John and I could resolve this discussion in 10 mins or less (or just plain agree to disagree). I'm game if you're interested John, but I am unable share my phone number here in a public place. Is there potentially a way we can share phone info privately, in a DM sort of way, here on Bugzilla?

In lieu of a phone call, it's unlikely I can continue offering effort to this discussion. Regardless, I sure do appreciate the attempt to hear me and resolve this. Thanks John! (Still hoping we can phone chat.)

[And since I can't edit my previous on this Bugzilla platform, it's difficult to refine and optimize my earlier writings. This is a major limiation of Bugzilla, imo--or maybe this community doesn't want to allow editing of previous comments--and I can understand potential reasons why, even if I (usually) disagree with them in these types of communities. ;-) ]

My impression is the majority of way too many people do not understand the real, overall picture (whatever is -- and frankly I'm still confused and should not be). The core of the issue is being perpetuated by some number of well-intentioned-but-ignorant developers, for whatever reason. And I think this could be partially solved by "pushing" a SHORT blurb of the the matter (legacy, current state, whatever) and putting said blurb where it's "hard to miss" (at the top of some community web pages or whatever) as an "initial README" of some sorts.

John writes:
"Regarding developers, I think they are well aware of the permission system."

This is NOT my experience.

John writes:
"Or are you suggesting, that a vast majority of them does not know about the Experiment permission? "

I don't know about a "vast majority." A small portion is too many. Ignorant (for good reasons) developers are out there saying "there's nothing I can do other request 'Everything' persmissions, Thunderbird forces me to do this." This problem is too easy to solve by just writing a few well-crafted sentences to describe history and current state of affairs. (Again... I would love this because I'm still confused.) I do not understand why there's so much pushback on this, but maybe the problem is just me.

Last point, then I need to disconnect and probably won't be able to reply for some time:

This is all vastly confusing to me as a NEW developer, and it need not be. This short blurb I propose (or however it's best solved) would massively clear things up for me, in just a few sentences.

Thanks again, gotta go. Later!

I can offer a zoom call next week, feel free to contact me at john@thunderbird.net to find a time slot.

Feedback from the community is important and we will try to improve.

Oh that's great, I emailed you (John). I will await your email reply. Thanks so much for all your effort, I tremendously appreciate it.

(I'm not sure if it's proper etiquette to have discussions like this on a bug/request thread, but I see no other way to have a "private-ish discussion" on Bugzilla. :-/ If such a way/method exists, pls let me know. :-) )

Status: UNCONFIRMED → RESOLVED
Closed: 3 years ago
Resolution: --- → WORKSFORME
You need to log in before you can comment on or make changes to this bug.