Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Third party lib clarification #1918

Merged
merged 8 commits into from
Aug 21, 2024
Merged

Third party lib clarification #1918

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
79daf8d
Add relevant policy text to the page
dotproto Jul 19, 2024
dd15bc3
Add standard styling for blockquotes
dotproto Jul 19, 2024
760a9f1
Apply suggestions from code review
dotproto Jul 22, 2024
50f35d9
Revert changes made to the policies page
dotproto Jul 22, 2024
8c80dc9
Revise intro and Q&A for clarity
dotproto Jul 30, 2024
363f994
Update src/content/documentation/publish/third-party-library-usage.md
dotproto Aug 2, 2024
6fe59bf
Revert style changes
dotproto Aug 1, 2024
f293dad
Update src/content/documentation/publish/third-party-library-usage.md
dotproto Aug 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions src/content/documentation/publish/third-party-library-usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,14 @@ 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.
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:

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.
* Extensions may only use the release versions of third party libraries.
* Third party libraries may not be modified.
Comment on lines +20 to +21
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is still duplicating content from the policies page. We should avoid that because we can't re-check all related pages when the policies are updated to find copies of provisions that were updated. Wouldn't a link to the policies section be enough, as you do in line 18?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I don't think so. This PR was created in response to a request from @mixedpuppy to quote the policy text on this page. The initial motivation for that request was that this page did not communicate the policy requirements to the reader despite the positioning that it is authoritative on the topic.

The other approach I was considering was to move the relevant policy text out of addons-policy.md and into a partial. That partial would then be imported in both addons-policy.md and third-party-library-usage.md. But since we don't have an existing pattern of using partials like this I held off.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I said in private, this is a best practices document, not a policies or requirements document. We should not duplicate official requirements into best practices documents. We can link to the policies where the requirements are stated, but the duplication is a recipe for failure, and we have to avoid that for content that touches policy provisions. There needs to be a single source of truth that we can we can reasonably keep up to date.


If you don't provide information about third-party libraries and the reviewer cannot evaluate your extension, it may be rejected.
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 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,
Expand All @@ -34,7 +37,7 @@ 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.
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,
Expand All @@ -52,7 +55,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**.

Expand Down Expand Up @@ -92,6 +95,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 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,
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.
Expand All @@ -107,5 +126,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
%}


Loading