1268610 - Document the ability to develop an add-on without a GUID and its consequences

Status: RESOLVED FIXED

(WebExtensions :: Untriaged, defect, P2)

Description

[Andy McKay]

Now that bug 1262005 has landed, I think we need to document this. There's quite a lot going on here that traverses across not just Firefox, but AMO and web-ext. In that:

* you can run an add-on with no id temporarily using about:debugging, great for testing
* you'll then be able to push it to AMO
* AMO will then assign you a guid
* you'll need to use that if you later want to update it through the API (not landed yet in web-ext)

Or if you wanted to, for example if you are migrating an old add-on, still specify a guid. And everything will use it.

I think this might require some good documentation and thinking about.

Comment 1

[Will Bamberg [:wbamberg]]

Some notes on this, so I don't forget.

From Firefox 48, you can install WebExtensions using about:debugging without needing an "applications" key in the manifest. This means you can develop using the same source as for Chrome.

When you're ready to submit the add-on to AMO, using the manual web interface, that XPI will not have to include "applications".  If it does not include "applications", then AMO will generate an ID for the add-on, and this will subsequently be used to track updates.

When you're ready to update your add-on on AMO, using the manual web interface, the updated XPI will again not have to include "applications": because you are using the add-ons page to update it, AMO knows which add-on you are updating.

I think the main goal here is that the manifest.json does not need to contain "application.id", so you can use the same source for Chrome and for Firefox. A secondary goal is not to have to know the add-on ID at all.

There are a few problems though:

1) the upload API requires that you pass the add-on ID. So if you're using that, rather than the manual web interface, then you need the know the ID.

2) "web-ext run" at the moment expects the manifest to contain "application.id". So if you're developing using web-ext, you need to know the add-on ID (and maintain a separate manifest.json, or at least have a system for building a different one for Firefox).

3) at the moment, the manual web interface on AMO actually *does* expect the XPI to contain "application.id".

***

For the docs, I think it might make sense to talk about two different basic workflows:

* the simple, manual one. In this you develop using about:debugging (and perhaps also "web-ext run", once (2) is fixed), and use the AMO web interface to submit and update the add-on. In this workflow you never have to know anything about add-on IDs. This is the workflow we'll cover in "getting started" type docs.

* the more automated version. In this you probably use web-ext to run and test the add-on, and use the AMO API to upload new versions. In this workflow you'll want to separate development and deployment: in development (once (2) is fixed) you don't need "application.id" in the manifest. In deployment, you'll need to have a record of the add-on ID, so you can pass it into the AMO API.

***

I think that until (3) is fixed in production, it doesn't really make sense to document any of this. I think that until (2) is fixed, it's hard to recommend web-ext.

Comment 2

[Andy McKay]

FYI Wil, this is live on AMO now, when we detect this scenario we set the minimum compat to 48. Just web-ext to go now.

Comment 3

[Will Bamberg [:wbamberg]]

Andy, I've made a few changes to try to address this, and also some related changes to promote use of "Load Temporary Add-on" over the old way. The general idea is to recommend a simple workflow where add-on developers:

* use "Load Temporary Add-on" for debugging (and only ever have to build XPIs when uploading to AMO, and never have to disable signing checks)
* don't ever deal with add-on IDs

So I've written three new pages:

* "WebExtensions and the Add-on ID" https://developer.mozilla.org/en-US/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID: this outlines the simple workflow where you never have to deal with the ID (or the "applications" key as a whole). It also describes when you do have to care about the ID. Pretty much everywhere else though, I'll act like applications/id does not exist.

* "Publishing your WebExtension": https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Publishing_your_WebExtension this is a pretty quick step-by-step guide to what to do once you've finished developing and are ready to publish. A big piece of this is to make this the only place we have to talk about zipping up your WebExtension. All the other docs can now talk only about the "Load Temporary Add-on" method.

* "Temporary Installation in Firefox": https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox: this is a standalone guide on using "Load Temporary Add-on" that we can refer to from everywhere else. This replaces the old doc, which described this method alongside the old disable-signing-and-make-an-XPI approach.

Then I've updated the "Getting Started" tutorial: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Your_first_WebExtension so it:

* no longer mentions the "applications" key
* only describes the "Load Temporary Add-on" method for testing
* refers people to the "Publishing your WebExtension" doc for next steps.

I've also updated the page on the "applications": https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/applications key to note that "id" is now optional, and to point people at "WebExtensions and the Add-on ID".

I know there will still be updates coming for web-ext, but if you had the chance I'd appreciate some review to check that everything here is correct and coherent and offers generally good advice.

Comment 4

[Andy McKay]

(In reply to Will Bamberg [:wbamberg] from comment #3)

> * "Publishing your WebExtension":
> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/
> Publishing_your_WebExtension this is a pretty quick step-by-step guide to
> what to do once you've finished developing and are ready to publish. A big
> piece of this is to make this the only place we have to talk about zipping
> up your WebExtension. All the other docs can now talk only about the "Load
> Temporary Add-on" method.

Is it worth mentioning that if its on AMO users will get updates and if not, then that's something the add-on author will have to take care of?

That's the only thing that I can think of, otherwise looks good. Thanks.

Comment 5

[Will Bamberg [:wbamberg]]

(In reply to Andy McKay [:andym] from comment #4)
> (In reply to Will Bamberg [:wbamberg] from comment #3)
> 
> > * "Publishing your WebExtension":
> > https://developer.mozilla.org/en-US/Add-ons/WebExtensions/
> > Publishing_your_WebExtension this is a pretty quick step-by-step guide to
> > what to do once you've finished developing and are ready to publish. A big
> > piece of this is to make this the only place we have to talk about zipping
> > up your WebExtension. All the other docs can now talk only about the "Load
> > Temporary Add-on" method.
> 
> Is it worth mentioning that if its on AMO users will get updates and if not,
> then that's something the add-on author will have to take care of?

Sounds good. I have added a bit on this.

> 
> That's the only thing that I can think of, otherwise looks good. Thanks.