1902610 - Clean up remaining deficits in the WebExtension schema files

Status: RESOLVED FIXED

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

Comment 1

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Use <em> for header names consistently in the schema files. r=mkmelin

The header names are mentioned for reference and thus should only be
emphasized.

Depends on D213540

Comment 2

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Follow Firefox and use <var> instead of <value> to represent variables or values. r=mkmelin

Our schema files use notations which were originally intended to be
interpreted by our documentation generator only. However, other
projects started to parse them as well and this patch moves towards a
notation used by Firefox, to increase interoperability of such projects.

Depends on D213744

Comment 3

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Switch to the reference notation used by Firefox, instead of the currently used reStructeredText notation. r=mkmelin

Our schema files use notations which were originally intended to be
interpreted by our documentation generator only. However, other
projects started to parse them as well and this patch moves towards a
notation used by Firefox, to increase interoperability of such projects.

Depends on D213745

Comment 4

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Replace reStructuredText double backtick notation for inline literals with <var>. r=mkmelin

Our schema files use notations which were originally intended to be
interpreted by our documentation generator only. However, other
projects started to parse them as well and this patch moves towards a
notation used by Firefox, to increase interoperability of such projects.

Depends on D213746

Comment 5

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Replace reStructuredText inline link notation by <a> tags, keeping placeholders for now. r=mkmelin

Our schema files use notations which were originally intended to be
interpreted by our documentation generator only. However, other
projects started to parse them as well and this patch moves towards a
notation used by Firefox, to increase interoperability of such projects.

We use link placeholders which are currently replaced by the
documentation generator. This patch is not touching them. We will
post-process the original schema files and include additional
information (for example, when an API method was added), and also split
the schema files for Manifest V2 and V3 for upstream consumers
(instead of doing that in the documentation generator). The
post-processor will also replace the links with their actual URLs. We
may re-evaluate this at a later time.

Depends on D213747

Comment 6

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Do not use "async": false for parent implementations. r=mkmelin

Using async: false causes parent implementations to return undefined
Immediately, before passing the function call through the process
boundary and executing the actual API function.

It is only useful for client implementations.

There is currently a chance, that the API returns before the folder has
actually been marked as read. This also allows us to actually switch to
an async parent implementation at a later time, without breaking
add-ons.

Depends on D213748

Comment 7

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Always use "async": "callback" for functions returning a value. r=mkmelin

Defining a callback function allows the schema validator to validate the
return value of the function in debug tests. This also allows add-ons
to use the chrome coding style, where callback functions are used
instead of Promises.

There are a few cases, where such a callback function had been defined
in the schema, but the method was not defined as having one.

Depends on D213757

Comment 8

[John Bieling (:TbSync)]

Attachment: Bug 1902610 - Rename the includeFolders parameter to includeSubFolders, improve the description and switch default for accounts.getDefault() in Manifest V3. r=standard8

Based on feedback from the community, this patch renames the parameter
and improves the description.

The patch also completes the switch of the default value for
accounts.getDefault(), which was missed.

Depends on D213762

Comment 9

[John Bieling (:TbSync)]

Try for the entire stack: https://treeherder.mozilla.org/jobs?repo=try-comm-central&revision=d19504a620ff249bc11b6b3730a197156d4af09b

Comment 10

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/comm-central/rev/19f85d2e0873
Use <em> for header names consistently in the schema files. r=mkmelin
https://hg.mozilla.org/comm-central/rev/68d43ca8095a
Follow Firefox and use <var> instead of <value> to represent variables or values. r=mkmelin
https://hg.mozilla.org/comm-central/rev/a115736fba5a
Switch to the reference notation used by Firefox, instead of the currently used reStructeredText notation. r=mkmelin
https://hg.mozilla.org/comm-central/rev/1e92fd020d49
Replace reStructuredText double backtick notation for inline literals with <var>. r=mkmelin
https://hg.mozilla.org/comm-central/rev/fdceda22857b
Replace reStructuredText inline link notation by <a> tags, keeping placeholders for now. r=mkmelin
https://hg.mozilla.org/comm-central/rev/4f80db0653cc
Do not use "async": false for parent implementations. r=mkmelin
https://hg.mozilla.org/comm-central/rev/04c0964eec6a
Always use "async": "callback" for functions returning a value. r=mkmelin
https://hg.mozilla.org/comm-central/rev/935779843ba0
Rename the includeFolders parameter to includeSubFolders, improve the description and switch default for accounts.getDefault() in Manifest V3. r=Standard8

Comment 11

[John Bieling (:TbSync)]

Comment on attachment 9407531 [details]
Bug 1902610 - Rename the includeFolders parameter to includeSubFolders, improve the description and switch default for accounts.getDefault() in Manifest V3. r=standard8

[Approval Request Comment]
Regression caused by (bug #): -
User impact if declined: This stack of patches is the final work on the official Manifest v3 support for ESR128, and a clean set of schema files. If these patches (the entire stack) is not uplifted, we will introduce backward incompatible changes in 129+, which should be avoided at all costs. ESR128 is the first version where we will declare Manifest V3 as stable, but these patches only landed in 129 and did not make it in time for 128.
Testing completed (on c-c, etc.): -
Risk to taking this patch (and alternatives if risky): Low

Comment 12

[Wayne Mery (:wsmwk)]

Comment on attachment 9407531 [details]
Bug 1902610 - Rename the includeFolders parameter to includeSubFolders, improve the description and switch default for accounts.getDefault() in Manifest V3. r=standard8

[Triage Comment]
Approved for beta

Rob, multiple patches to uplift in this bug

Comment 13

[Rob Lemley [:rjl]]

Thunderbird 128.0b2:
https://hg.mozilla.org/releases/comm-beta/rev/63b504bd1079
https://hg.mozilla.org/releases/comm-beta/rev/6f24a05e342f
https://hg.mozilla.org/releases/comm-beta/rev/1bfe4d57a62a
https://hg.mozilla.org/releases/comm-beta/rev/7a1e3285fb7d
https://hg.mozilla.org/releases/comm-beta/rev/8b9133b2b81e
https://hg.mozilla.org/releases/comm-beta/rev/19c52d1fa758
https://hg.mozilla.org/releases/comm-beta/rev/23d89d6a87af
https://hg.mozilla.org/releases/comm-beta/rev/6b861c2697b3