From 79daf8dca592c46b313d7428b595bc08532b6a42 Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Fri, 19 Jul 2024 14:28:50 -0700 Subject: [PATCH 1/8] Add relevant policy text to the page --- src/content/documentation/publish/add-on-policies.md | 3 +-- .../documentation/publish/third-party-library-usage.md | 6 +++++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/content/documentation/publish/add-on-policies.md b/src/content/documentation/publish/add-on-policies.md index 47c662e42..547f62075 100644 --- a/src/content/documentation/publish/add-on-policies.md +++ b/src/content/documentation/publish/add-on-policies.md @@ -127,7 +127,6 @@ In general, developers are free to maintain their add-ons in the manner they cho The following requirements are of particular importance: - - Add-ons must only request those permissions that are necessary for them to function. - Add-ons must be self-contained and not load remote code for execution. - Add-ons must not load or redirect to a remote new tab page. The new tab page must be contained within the add-on. @@ -135,7 +134,7 @@ The following requirements are of particular importance: - Add-ons must use encryption when transporting data remotely. - Add-ons should avoid including redundant code or files. - Add-ons must not negatively impact the performance or stability of Firefox. -- Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted. Please read our [third party library guidelines](/documentation/publish/third-party-library-usage/) to better understand related requirements. +- Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted. Please read our [third party library guidelines](/documentation/publish/third-party-library-usage/) to better understand related requirements. {% comment %}Changes to this line should also be copied to /src/content/documentation/publish/third-party-library-usage.md{% endcomment %} {% endcapture %} {% include modules/one-column.liquid, diff --git a/src/content/documentation/publish/third-party-library-usage.md b/src/content/documentation/publish/third-party-library-usage.md index fb93b0254..68ca65d2c 100644 --- a/src/content/documentation/publish/third-party-library-usage.md +++ b/src/content/documentation/publish/third-party-library-usage.md @@ -15,7 +15,11 @@ date: 2022-10-17 # Third Party Library Usage -To complete the review process at [addons.mozilla.org](https://addons.mozilla.org) (AMO), reviewers must be able to verify the code in your extension. You may include third-party libraries in your extension. In that case, when you upload your extension to AMO, you will need to provide links to the library source code. +> Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted. +> +> [Development Practices](/documentation/publish/add-on-policies/#development-practices), [Add-ons Policies](/documentation/publish/add-on-policies/) + +To complete the review process at [addons.mozilla.org](https://addons.mozilla.org) (AMO), reviewers must be able to verify the code in your extension. If you include third-party libraries in your extension, you will need to provide links to the library source code as part of the AMO submission process. If your add-on uses minified, obfuscated or otherwise machine-generated first-party code, please see [our requirements](/documentation/publish/source-code-submission/) for that. From dd15bc3ddb4a9ea87aafd39f7cf461147189218a Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Fri, 19 Jul 2024 14:30:10 -0700 Subject: [PATCH 2/8] Add standard styling for blockquotes --- src/assets/css/_settings.scss | 4 ++-- src/content/documentation/develop/known-issues.md | 10 +++------- 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/src/assets/css/_settings.scss b/src/assets/css/_settings.scss index f115432db..4e8e860b3 100644 --- a/src/assets/css/_settings.scss +++ b/src/assets/css/_settings.scss @@ -330,8 +330,8 @@ $defnlist-margin-bottom: 1rem; $defnlist-term-weight: $global-weight-bold; $defnlist-term-margin-bottom: 0.3rem; $blockquote-color: $dark-gray; -$blockquote-padding: rem-calc(15 0); -$blockquote-border: 0; +$blockquote-padding: rem-calc(16 0 16 16); +$blockquote-border: 5px solid #aaa; $cite-font-size: rem-calc(13); $cite-color: $black; $cite-pseudo-content: ''; diff --git a/src/content/documentation/develop/known-issues.md b/src/content/documentation/develop/known-issues.md index 3c039ceba..eb3975027 100644 --- a/src/content/documentation/develop/known-issues.md +++ b/src/content/documentation/develop/known-issues.md @@ -72,13 +72,9 @@ This page contains a list of significant known issues that affect the experience **Description:** While debugging an extension on Android, you may encounter an error in Firefox on your desktop that says something like: -
- -Cannot connect to the debug target. See error details below:

- -`Error: Protocol error (Error): Attempted to write a response containing a destroyed actor from: root (resource://devtools/shared/protocol/types.js:358:17)` - -
+> Cannot connect to the debug target. See error details below: +> +> `Error: Protocol error (Error): Attempted to write a response containing a destroyed actor from: root (resource://devtools/shared/protocol/types.js:358:17)` **Workaround:** In the `about:debugging` page on your development computer, disconnect from and reconnect to the Android device. From 760a9f156965ccb424237d7a242a0eb2c5ca73dd Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Mon, 22 Jul 2024 16:12:07 -0700 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: rebloor --- .../documentation/publish/third-party-library-usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/documentation/publish/third-party-library-usage.md b/src/content/documentation/publish/third-party-library-usage.md index 68ca65d2c..0317d14e4 100644 --- a/src/content/documentation/publish/third-party-library-usage.md +++ b/src/content/documentation/publish/third-party-library-usage.md @@ -17,9 +17,9 @@ date: 2022-10-17 > Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted. > -> [Development Practices](/documentation/publish/add-on-policies/#development-practices), [Add-ons Policies](/documentation/publish/add-on-policies/) +> See [Development Practices](/documentation/publish/add-on-policies/#development-practices) and [Add-ons Policies](/documentation/publish/add-on-policies/) for more information. -To complete the review process at [addons.mozilla.org](https://addons.mozilla.org) (AMO), reviewers must be able to verify the code in your extension. If you include third-party libraries in your extension, you will need to provide links to the library source code as part of the AMO submission process. +To complete the [addons.mozilla.org](https://addons.mozilla.org) (AMO) review process, reviewers must be able to verify the code in your extension. If you include third-party libraries in your extension, you must provide links to the library source code as part of the AMO submission process. If your add-on uses minified, obfuscated or otherwise machine-generated first-party code, please see [our requirements](/documentation/publish/source-code-submission/) for that. From 50f35d91623435e17a45346ab673952b63ff0b1c Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Mon, 22 Jul 2024 16:20:50 -0700 Subject: [PATCH 4/8] Revert changes made to the policies page --- src/content/documentation/publish/add-on-policies.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/documentation/publish/add-on-policies.md b/src/content/documentation/publish/add-on-policies.md index 547f62075..47c662e42 100644 --- a/src/content/documentation/publish/add-on-policies.md +++ b/src/content/documentation/publish/add-on-policies.md @@ -127,6 +127,7 @@ In general, developers are free to maintain their add-ons in the manner they cho The following requirements are of particular importance: + - Add-ons must only request those permissions that are necessary for them to function. - Add-ons must be self-contained and not load remote code for execution. - Add-ons must not load or redirect to a remote new tab page. The new tab page must be contained within the add-on. @@ -134,7 +135,7 @@ The following requirements are of particular importance: - Add-ons must use encryption when transporting data remotely. - Add-ons should avoid including redundant code or files. - Add-ons must not negatively impact the performance or stability of Firefox. -- Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted. Please read our [third party library guidelines](/documentation/publish/third-party-library-usage/) to better understand related requirements. {% comment %}Changes to this line should also be copied to /src/content/documentation/publish/third-party-library-usage.md{% endcomment %} +- Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted. Please read our [third party library guidelines](/documentation/publish/third-party-library-usage/) to better understand related requirements. {% endcapture %} {% include modules/one-column.liquid, From 8c80dc961fd023777541a940316992978a4ad38b Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Tue, 30 Jul 2024 12:12:13 -0700 Subject: [PATCH 5/8] Revise intro and Q&A for clarity --- .../publish/third-party-library-usage.md | 35 +++++++++++++------ 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/src/content/documentation/publish/third-party-library-usage.md b/src/content/documentation/publish/third-party-library-usage.md index 0317d14e4..406df5d43 100644 --- a/src/content/documentation/publish/third-party-library-usage.md +++ b/src/content/documentation/publish/third-party-library-usage.md @@ -15,15 +15,14 @@ date: 2022-10-17 # Third Party Library Usage -> Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted. -> -> See [Development Practices](/documentation/publish/add-on-policies/#development-practices) and [Add-ons Policies](/documentation/publish/add-on-policies/) for more information. +The [Development Practices](/documentation/publish/add-on-policies/#development-practices) section of the [Add-ons Policies](/documentation/publish/add-on-policies/) states that you can include third party libraries in your extension as long the following conditions are met: -To complete the [addons.mozilla.org](https://addons.mozilla.org) (AMO) review process, reviewers must be able to verify the code in your extension. If you include third-party libraries in your extension, you must provide links to the library source code as part of the AMO submission process. +* Extensions may only use the release versions of third party libraries. +* Third party libraries may not be modified. -If your add-on uses minified, obfuscated or otherwise machine-generated first-party code, please see [our requirements](/documentation/publish/source-code-submission/) for that. +In order for reviewers to verify that these requirements are met, you must provide links to the library source code as part of the AMO submission process. If you don't provide information about third-party libraries and the reviewer cannot evaluate your extension, it may be rejected. -If you don't provide information about third-party libraries and the reviewer cannot evaluate your extension, it may be rejected. +If your extension uses minified, obfuscated or otherwise machine-generated first-party code, please see [our requirements](/documentation/publish/source-code-submission/) for that. {% endcapture %} {% include modules/page-hero.liquid, @@ -38,7 +37,9 @@ If you don't provide information about third-party libraries and the reviewer ca ## When must links for third-party libraries be provided? -You must provide a link to the source code for any third-party libraries included in your extension, minified or not. +Links to third party libraries must be provided when submitting the extension. The links may either be included in the extension's archive, the source archive, or in the "notes for reviewers" on the submission. + +If you include links in one of the archives, we recommend either adding them to a README file in the root directory or another root file clearly intended for AMO reviewers. {% endcapture %} {% include modules/column-w-toc.liquid, @@ -56,7 +57,7 @@ You must provide a link to the source code for any third-party libraries include You must provide links to the original copies of the files included in your extension and links to the readable source code for those files. For repositories or version controlled files, please specify the link using release tag that you’ve used. Note that non-release versions of third-party libraries are not accepted. -You should download third-party libraries from their official site, not from a CDN or other location. This point is important. Reviewers confirm that your code contains the original library using checksums. Unofficial sources often make small changes to a library’s files, such as whitespace changes, so the checksums don't match. +You should download third-party libraries from their official site, not from a CDN or other location. This point is important. Reviewers confirm that your code contains the original library using checksums, so the version in the extension must be identical to the official distribution. Unofficial sources often make small changes to a library’s files, such as whitespace changes, so the checksums don't match. Example: If you’re using the minified version of mousetrap release 1.4.2 (because you haven’t had the chance to update to the latest version) the following links are **incorrect**. @@ -96,6 +97,22 @@ Tip: If the library is on GitHub, you can usually find this version under the {% capture content %} +## Use of package managers + +Extensions developers can use package managers and package repositories like [npm](https://www.npmjs.com/) to retrieve third party libraries. + +With a default npm configuration, third party library dependencies are declared in the project's `package.json` file: this qualifies as a third party library link as [previously described](#how-to-determine-the-third-party-library-link). + +Reviewers must be be able to retrieve and review all packages used by your extension, so the use of private packages or non-public registries is not recommended. If you do, you will need to provide reviewers with access to the private packages. Access information should be provided along with build instructions as part of the [source code submission](https://extensionworkshop.com/documentation/publish/source-code-submission/) process. + +{% endcapture %} +{% include modules/one-column.liquid, + id: "use-of-package-managers" + content: content +%} + +{% capture content %} + ## Communicating third-party library links to the reviewer You can add the links to the “Notes for Reviewers” section of your extension’s details on AMO. @@ -111,5 +128,3 @@ If you miss any of the necessary information for used third-party libraries, the id: "communicating-third-party-library-links-to-the-reviewer" content: content %} - - From 363f9948dd422b5000b1c7f6bd5beac34c288f23 Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Fri, 2 Aug 2024 15:49:39 -0700 Subject: [PATCH 6/8] Update src/content/documentation/publish/third-party-library-usage.md Co-authored-by: rebloor --- .../documentation/publish/third-party-library-usage.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/content/documentation/publish/third-party-library-usage.md b/src/content/documentation/publish/third-party-library-usage.md index 406df5d43..4e300e879 100644 --- a/src/content/documentation/publish/third-party-library-usage.md +++ b/src/content/documentation/publish/third-party-library-usage.md @@ -37,9 +37,7 @@ If your extension uses minified, obfuscated or otherwise machine-generated first ## When must links for third-party libraries be provided? -Links to third party libraries must be provided when submitting the extension. The links may either be included in the extension's archive, the source archive, or in the "notes for reviewers" on the submission. - -If you include links in one of the archives, we recommend either adding them to a README file in the root directory or another root file clearly intended for AMO reviewers. +When submitting a version to AMO, links to third-party libraries must be provided. You can add the links to the "Notes for Reviewers" section of your extension's details. {% endcapture %} {% include modules/column-w-toc.liquid, From 6fe59bf158964f87d55d08fe75f7762eb6e12e4b Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Wed, 31 Jul 2024 18:28:30 -0700 Subject: [PATCH 7/8] Revert style changes These edits will be migrated into another branch. --- src/assets/css/_settings.scss | 4 ++-- src/content/documentation/develop/known-issues.md | 10 +++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/src/assets/css/_settings.scss b/src/assets/css/_settings.scss index 4e8e860b3..f115432db 100644 --- a/src/assets/css/_settings.scss +++ b/src/assets/css/_settings.scss @@ -330,8 +330,8 @@ $defnlist-margin-bottom: 1rem; $defnlist-term-weight: $global-weight-bold; $defnlist-term-margin-bottom: 0.3rem; $blockquote-color: $dark-gray; -$blockquote-padding: rem-calc(16 0 16 16); -$blockquote-border: 5px solid #aaa; +$blockquote-padding: rem-calc(15 0); +$blockquote-border: 0; $cite-font-size: rem-calc(13); $cite-color: $black; $cite-pseudo-content: ''; diff --git a/src/content/documentation/develop/known-issues.md b/src/content/documentation/develop/known-issues.md index eb3975027..3c039ceba 100644 --- a/src/content/documentation/develop/known-issues.md +++ b/src/content/documentation/develop/known-issues.md @@ -72,9 +72,13 @@ This page contains a list of significant known issues that affect the experience **Description:** While debugging an extension on Android, you may encounter an error in Firefox on your desktop that says something like: -> Cannot connect to the debug target. See error details below: -> -> `Error: Protocol error (Error): Attempted to write a response containing a destroyed actor from: root (resource://devtools/shared/protocol/types.js:358:17)` +
+ +Cannot connect to the debug target. See error details below:

+ +`Error: Protocol error (Error): Attempted to write a response containing a destroyed actor from: root (resource://devtools/shared/protocol/types.js:358:17)` + +
**Workaround:** In the `about:debugging` page on your development computer, disconnect from and reconnect to the Android device. From f293dadb1fd1c03d1425f2eb977e9b4aae7034ab Mon Sep 17 00:00:00 2001 From: Simeon Vincent Date: Fri, 2 Aug 2024 16:12:14 -0700 Subject: [PATCH 8/8] Update src/content/documentation/publish/third-party-library-usage.md Co-authored-by: rebloor --- .../documentation/publish/third-party-library-usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/documentation/publish/third-party-library-usage.md b/src/content/documentation/publish/third-party-library-usage.md index 4e300e879..3ac07b0e1 100644 --- a/src/content/documentation/publish/third-party-library-usage.md +++ b/src/content/documentation/publish/third-party-library-usage.md @@ -37,7 +37,7 @@ If your extension uses minified, obfuscated or otherwise machine-generated first ## When must links for third-party libraries be provided? -When submitting a version to AMO, links to third-party libraries must be provided. You can add the links to the "Notes for Reviewers" section of your extension's details. +When submitting a version to AMO, links to third-party libraries must be provided. You can add the links to the "Notes for Reviewers" section of your extension's details. {% endcapture %} {% include modules/column-w-toc.liquid, @@ -101,7 +101,7 @@ Extensions developers can use package managers and package repositories like [np With a default npm configuration, third party library dependencies are declared in the project's `package.json` file: this qualifies as a third party library link as [previously described](#how-to-determine-the-third-party-library-link). -Reviewers must be be able to retrieve and review all packages used by your extension, so the use of private packages or non-public registries is not recommended. If you do, you will need to provide reviewers with access to the private packages. Access information should be provided along with build instructions as part of the [source code submission](https://extensionworkshop.com/documentation/publish/source-code-submission/) process. +Reviewers must be able to retrieve and review all packages used by your extension. Therefore, the use of private packages or non-public registries is permissible but not recommended. If you use non-public dependencies, you must include the relevant `node_modules` sub-directories in your [source code submission](/documentation/publish/source-code-submission/). {% endcapture %} {% include modules/one-column.liquid,