From fbaf0bb26397aa498eb9156f06d5a6fe34dd7dd8 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 03:14:29 +0200 Subject: Merging upstream version 125.0.1. Signed-off-by: Daniel Baumann --- docs/bug-mgmt/processes/accessibility-review.md | 9 +- docs/code-quality/lint/create.rst | 4 + .../rules/import-headjs-globals.rst | 1 - .../rules/no-more-globals.rst | 20 +++ .../rules/reject-mixing-eager-and-lazy.rst | 11 +- .../rules/reject-relative-requires.rst | 2 +- .../eslint-plugin-mozilla/rules/valid-lazy.rst | 10 +- docs/code-quality/lint/linters/ignorefile.rst | 45 ++++++ docs/conf.py | 1 + docs/config.yml | 1 + docs/contributing/index.rst | 8 ++ docs/contributing/reviews.rst | 6 + docs/contributing/signing/signing_macos_build.rst | 155 +++++++++++++++++++++ docs/setup/configuring_build_options.rst | 12 ++ 14 files changed, 271 insertions(+), 14 deletions(-) create mode 100644 docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/no-more-globals.rst create mode 100644 docs/code-quality/lint/linters/ignorefile.rst create mode 100644 docs/contributing/signing/signing_macos_build.rst (limited to 'docs') diff --git a/docs/bug-mgmt/processes/accessibility-review.md b/docs/bug-mgmt/processes/accessibility-review.md index 3358defd7e..090d83acfe 100644 --- a/docs/bug-mgmt/processes/accessibility-review.md +++ b/docs/bug-mgmt/processes/accessibility-review.md @@ -54,9 +54,12 @@ bug for the accessibility review. Otherwise, particularly for smaller changes, you may do this on an existing bug. Note that if you file a new bug, you will need to submit the bug and then edit it to set the flag. -Once the review is done, the accessibility team will set the a11y-review -flag depending on the outcome: - +During the review process, the accessibility team will modify the a11y-review +flag: +- assigned: The review has been triaged by the team and an engineer has been assigned + to the review. If the flag has been set on a bug filed specifically for the purposes + of review (i.e., the bug does not have additional engineering work attached, and the bug is not a meta bug) the review assignee will assign the bug to themselves. + Otherwise, they'll comment on the bug so you know who they are :) - passed: Either no changes are required, or some changes are required but the accessibility team does not believe it is necessary to review or verify those changes prior to shipping. Generally, a review will not be passed if diff --git a/docs/code-quality/lint/create.rst b/docs/code-quality/lint/create.rst index c4d8b15480..4da59b83a0 100644 --- a/docs/code-quality/lint/create.rst +++ b/docs/code-quality/lint/create.rst @@ -80,11 +80,15 @@ Each ``.yml`` file must have at least one linter defined in it. Here are the sup * include - A list of file paths that will be considered (optional) * exclude - A list of file paths or glob patterns that must not be matched (optional) * extensions - A list of file extensions to be considered (optional) +* exclude_extensions - A list of file extensions to be excluded (optional) * setup - A function that sets up external dependencies (optional) * support-files - A list of glob patterns matching configuration files (optional) * find-dotfiles - If set to ``true``, run on dot files (.*) (optional) * ignore-case - If set to ``true`` and ``type`` is regex, ignore the case (optional) +Note that a linter may not have both ``extensions`` and ``exclude_extensions`` specified at the +same time. + In addition to the above, some ``.yml`` files correspond to a single lint rule. For these, the following additional keys may be specified: diff --git a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/import-headjs-globals.rst b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/import-headjs-globals.rst index df8ef81300..51ec8eeb62 100644 --- a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/import-headjs-globals.rst +++ b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/import-headjs-globals.rst @@ -19,7 +19,6 @@ If path does not exist because it is generated e.g. The following patterns are supported: -- ``Cu.import("resource://devtools/client/shared/widgets/ViewHelpers.jsm");`` - ``loader.lazyRequireGetter(this, "name2"`` - ``loader.lazyServiceGetter(this, "name3"`` - ``loader.lazyGetter(this, "toolboxStrings"`` diff --git a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/no-more-globals.rst b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/no-more-globals.rst new file mode 100644 index 0000000000..2cbe7e82ab --- /dev/null +++ b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/no-more-globals.rst @@ -0,0 +1,20 @@ +no-more-globals +=============== + +This rule is used to discourage people from adding ever more global variables to +files where the rule is run. + +For any file ``example.js`` where the rule is applied, the rule will read +an allowlist of globals from a sibling ``example.js.globals`` file. The rule +will warn for any globals defined in ``example.js`` that are not listed in the +``globals`` file, and will also warn for any items on the allowlist in +the ``globals`` file that are no longer present in ``example.js``, encouraging +people to remove them from the ``globals`` list. + +If you see errors from this rule about new globals, **do not just add items to +the allowlist**. Instead, work to find a way to run your code so that it does +not add to the list of globals. + +If you see errors when removing globals, simply remove them from the allowlist +to make sure it is up-to-date and things do not inadvertently end up getting +put back in. diff --git a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-mixing-eager-and-lazy.rst b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-mixing-eager-and-lazy.rst index 51524f4e14..1b7c165036 100644 --- a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-mixing-eager-and-lazy.rst +++ b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-mixing-eager-and-lazy.rst @@ -9,9 +9,10 @@ Examples of incorrect code for this rule: .. code-block:: js - const { SomeProp } = ChromeUtils.import("resource://gre/modules/Foo.jsm"); - ChromeUtils.defineLazyModuleGetters(lazy, { - OtherProp: "resource://gre/modules/Foo.jsm", + const { SomeProp } = + ChromeUtils.importESModule("resource://gre/modules/Foo.sys.mjs"); + ChromeUtils.defineESModuleGetters(lazy, { + OtherProp: "resource://gre/modules/Foo.sys.mjs", }); Examples of correct code for this rule: @@ -19,4 +20,6 @@ Examples of correct code for this rule: .. code-block:: js - const { SomeProp, OtherProp } = ChromeUtils.import("resource://gre/modules/Foo.jsm"); + const { SomeProp, OtherProp } = ChromeUtils.importESModule( + "resource://gre/modules/Foo.sys.mjs" + ); diff --git a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-relative-requires.rst b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-relative-requires.rst index 4387041b26..c3ec0cfed8 100644 --- a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-relative-requires.rst +++ b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-relative-requires.rst @@ -18,5 +18,5 @@ Examples of correct code for this rule: .. code-block:: js require("devtools/absolute/path") - require("resource://gre/modules/SomeModule.jsm") + require("resource://gre/modules/SomeModule.sys.mjs") loader.lazyRequireGetter(this, "path", "devtools/absolute/path", true) diff --git a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/valid-lazy.rst b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/valid-lazy.rst index a7edeeb5fc..e7f6706d5b 100644 --- a/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/valid-lazy.rst +++ b/docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/valid-lazy.rst @@ -19,10 +19,10 @@ Examples of incorrect code for this rule: .. code-block:: js const lazy = {}; - ChromeUtils.defineLazyGetter(lazy, "foo", "foo.jsm"); + ChromeUtils.defineESModuleGetters(lazy, { foo: "foo.sys.mjs"}); // Duplicate symbol foo being added to lazy. - ChromeUtils.defineLazyGetter(lazy, "foo", "foo1.jsm"); + ChromeUtils.defineLazyGetter(lazy, "foo", () => {}); if (x) { lazy.foo3.bar(); } @@ -31,12 +31,12 @@ Examples of incorrect code for this rule: const lazy = {}; // Unused lazy property foo - ChromeUtils.defineLazyGetter(lazy, "foo", "foo.jsm"); + ChromeUtils.defineESModuleGetters(lazy, { foo: "foo.sys.mjs"}); .. code-block:: js const lazy = {}; - ChromeUtils.defineLazyGetter(lazy, "foo", "foo.jsm"); + ChromeUtils.defineESModuleGetters(lazy, { foo: "foo.sys.mjs"}); // Used at top-level unconditionally. lazy.foo.bar(); @@ -47,7 +47,7 @@ Examples of correct code for this rule: const lazy = {}; ChromeUtils.defineLazyGetter(lazy, "foo1", () => {}); - XPCOMUtils.defineLazyModuleGetters(lazy, { foo2: "foo2.jsm" }); + ChromeUtils.defineESModuleGetters(lazy, { foo2: "foo2.sys.mjs"}); if (x) { lazy.foo1.bar(); diff --git a/docs/code-quality/lint/linters/ignorefile.rst b/docs/code-quality/lint/linters/ignorefile.rst new file mode 100644 index 0000000000..506ea5de51 --- /dev/null +++ b/docs/code-quality/lint/linters/ignorefile.rst @@ -0,0 +1,45 @@ +Ignorefile Lint +=============== + +Ignorefile lint is a linter for ``.gitignore`` and ``.hgignore`` files, +to verify those files have equivalent entries. + +Each pattern is roughly compared, ignoring punctuations, to absorb the +syntax difference. + +Run Locally +----------- + +The mozlint integration of ignorefile linter can be run using mach: + +.. parsed-literal:: + + $ mach lint --linter ignorefile + + +Special syntax +-------------- + +The following special comment can be used to ignore the pattern in the next line. + +.. parsed-literal:: + + # lint-ignore-next-line: git-only + # lint-ignore-next-line: hg-only + +The next line exists only in ``.gitignore``. or ``.hgignore``. + +.. parsed-literal:: + # lint-ignore-next-line: syntax-difference + +The next line's pattern needs to be represented differently between +``.gitignore`` and ``.hgignore``. +This can be used when the ``.hgignore`` uses complex pattern which cannot be +represented in single pattern in ``.gitignore``. + + +Sources +------- + +* :searchfox:`Configuration (YAML) ` +* :searchfox:`Source ` diff --git a/docs/conf.py b/docs/conf.py index 22952239a9..30c341e531 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,6 +54,7 @@ extensions = [ # When adding more paths to this list, please ensure that they are not # excluded from valid-jsdoc in the top-level .eslintrc.js. js_source_path = [ + "../browser/components/backup", "../browser/components/extensions", "../browser/components/migration", "../browser/components/migration/content", diff --git a/docs/config.yml b/docs/config.yml index 823451c51e..0a4ed464d0 100644 --- a/docs/config.yml +++ b/docs/config.yml @@ -33,6 +33,7 @@ categories: - uriloader - widget/cocoa - widget/windows + - toolkit/components/ml - accessible - code-quality - writing-rust-code diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 545e161f8e..3321b7f5f4 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -41,6 +41,14 @@ development process and source code documentation. debugging/* +.. toctree:: + :caption: Signing + :maxdepth: 1 + :glob: + + signing/* + + .. toctree:: :caption: Additional Information :maxdepth: 1 diff --git a/docs/contributing/reviews.rst b/docs/contributing/reviews.rst index d2424724a2..8cd968ced3 100644 --- a/docs/contributing/reviews.rst +++ b/docs/contributing/reviews.rst @@ -68,6 +68,9 @@ Review groups * - #firefox-svg-reviewers - SVG-related changes - `Member list `__ + * - #android-reviewers + - Changes to Fenix, Focus and Android Components. + - `Member list `__ * - #geckoview-reviewers - Changes to GeckoView - `Member list `__ @@ -131,6 +134,9 @@ Review groups * - #style or #firefox-style-system-reviewers - Firefox style system (servo, layout/style). - `Member list `__ + * - #supply-chain-reviewers + - Changes to third-party audits and vendoring (cargo-vet, supply_chain). + - `Member list `__ * - #webcompat-reviewers - System addons maintained by the Web Compatibility team - `Member list `__ diff --git a/docs/contributing/signing/signing_macos_build.rst b/docs/contributing/signing/signing_macos_build.rst new file mode 100644 index 0000000000..688a935bbe --- /dev/null +++ b/docs/contributing/signing/signing_macos_build.rst @@ -0,0 +1,155 @@ +Signing Local macOS Builds +========================== + +Background +---------- +Firefox for macOS is mainly signed in one of two different ways: one for +production releases, and one for builds that run on try. Typically, developers +testing local builds don’t need to be concerned with signing unless they are +working on an area specifically affected by macOS entitlements such as passkeys, +loading third party libraries, or adding a new process type. However, it is +good practice to test builds that are as close as possible to the production +configuration or the try server configuration. Local builds are not signed +automatically and mach doesn’t include support for running tests on signed +builds. However, the mach command ``macos-sign`` can be used to sign local +packaged builds for manual testing. ``macos-sign`` supports signing builds to +match try or production builds. + + Note: On Apple Silicon Macs, where all executables are required to be + signed, Firefox binaries will be “ad-hoc” self-signed automatically by the + linker during compilation, but this is a per-binary sign with no + Firefox-specific runtime settings or entitlements. This document ignores + automatic signing. + +To sign your own local build so that it has the same set of entitlements as a +production release requires a signing certificate and provisioning profile +issued from Mozilla’s Apple Developer account. Entitlements are used to grant +Firefox certain permissions as well as impose security restrictions when it is +run on macOS. Some entitlements are considered restricted and can only be +enabled when signed by a certificate from an account that has been granted +permission to use the entitlement, such as the passkey macOS entitlement. As an +example of the production restrictions, production builds use an entitlement +that disallows debugger attachment. Disallowing debuggers is required for +distribution because it is required by the Notarization system. When signing +locally, developers can modify entitlements as needed. + +Summary +------- + +**Production build:** requires Mozilla's official Apple Developer ID +certificate, private key, and provisioning profile. Only Mozilla Release +Engineering has access to the official Developer ID certificate and private key. +Mozilla developers can request a limited-use Apple *Developer* certificate which +can be used to generated production-like builds for local testing. See +:ref:`like-prod` below. + +**Developer build:** requires generating a self-signed certificate (to sign +like a try push is signed) or using ad-hoc signing (no setup required and only +usable locally), will have no passkey support (or any other restricted +entitlement), has fewer restrictions with respect to module loading, is +debuggable. + +Signing Your Build Like try +--------------------------- +To sign your own local build with entitlements that match what is used for try +push automated testing, generate a self-signed code signing certificate using +the macOS Keychain Access application. During the process, supply a unique name +not used by other Keychain entries making sure to not use any spaces. For +example, ``my-firefox-selfsign-cert-2024``. This string will be used as +the signing identity and passed to ``macos-sign`` with the ``-s`` option. +``./mach`` passes this to the codesign command which looks up the entry in the +keychain. When running the signing command, you'll be prompted to allow +``codesign`` to access the keychain entry. Select ``Always Allow`` when +prompted. + +.. code-block:: shell + + $ ./mach build package + $ open + + $ ./mach macos-sign -s my-firefox-selfsign-cert-2024 -a ~/Desktop/Nightly.app + +The entitlements in the tree used for this configuration are labeled as +developer and we call this the developer build. Developer signed builds differ +from production signed in the following ways: + +* They allow debugger attachment +* They allow loading of third party libraries in all processes +* They respect dyld environment variables +* They don’t include restricted entitlements such as the passkey entitlement + (and therefore passkeys can’t be used) + +Ad-hoc Signing Your Build - Like try Signing, but Requires no Configuration and is For Local Use Only +----------------------------------------------------------------------------------------------------- +Omitting the ``-s`` option will use ad-hoc signing which requires no setup. The +build will be more limited than builds signed with a self-signed cert. Ad-hoc +signed builds are not verifiable or runnable on any other system. There is +little documentation available about the limitations. + +.. code-block:: shell + + $ ./mach build package + $ open + + $ ./mach macos-sign -a ~/Desktop/Nightly.app + +.. _like-prod: + +Signing Your Build Like Production +---------------------------------- +To sign your local build like a production Firefox build, you’ll need an Apple +Developer signing certificate and provisioning profile issued from Mozilla's +Apple Developer account. Developers will be given a development-role login +allowing a signing certificate and provisioning profile to be generated. The +provisioning profile used with Development certificates limits the signed +application to Mozilla developer machines via a hardware ID. Employees can file +a bug `here `__ +to request an account. Once the developer's Apple account is setup as a member +of Mozilla's Apple account, Xcode can be used to download a Developer signing +certificate and provisioning profile for development use. Use Keychain Access to +get the codesigning identifier for your development cert which should be passed +as the ``-s`` codesigning identity to ``mach macos-sign``: + +.. code-block:: shell + + $ ./mach build package + $ open + + $ ./mach macos-sign -a ~/Desktop/Nightly.app -s + +Example: Re-Signing Official Nightly +------------------------------------ + +.. code-block:: shell + + $ ditto /Applications/Firefox\ Nightly.app ~/Desktop/FirefoxNightly.app + $ ./mach macos-sign -a ~/Desktop/FirefoxNightly.app + 0:00.20 Using ad-hoc signing identity + 0:00.20 Using nightly channel signing configuration + 0:00.20 Using developer entitlements + 0:00.20 Reading build config file /Users/me/r/mc/taskcluster/ci/config.yml + 0:00.23 Stripping existing xattrs and signatures + 0:01.91 Signing with codesign + 0:02.72 Verification of signed app /Users/me/Desktop/FirefoxNightly.app OK + +Example: Re-Signing Official Developer Edition With `rcodesign `__ Using a pkcs12 Certificate Key Pair +----------------------------------------------------------------------------------------------------------------------------------------------- + +More information about rcodesign can be found on the +`rust crate page `__ or +`github repo `__. Certificates +can be exported from Keychain Access in .p12 format. + +.. code-block:: shell + + $ ditto /Applications/Firefox\ Developer\ Edition.app/ ~/Desktop/DevEdition.app + $ ./mach macos-sign -r -a ~/Desktop/DevEdition.app \ + --rcodesign-p12-file ./myDevId.p12 \ + --rcodesign-p12-password-file ./myDevId.p12.passwd + 0:00.26 Using pkcs12 signing identity + 0:00.26 Using devedition channel signing configuration + 0:00.26 Using developer entitlements + 0:00.26 Reading build config file /Users/me/r/mc/taskcluster/ci/config.yml + 0:00.29 Stripping existing xattrs and signatures + 0:02.09 Signing with rcodesign + 0:11.16 Verification of signed app /Users/me/Desktop/DevEdition.app OK diff --git a/docs/setup/configuring_build_options.rst b/docs/setup/configuring_build_options.rst index 0afded76cd..fcd27d4869 100644 --- a/docs/setup/configuring_build_options.rst +++ b/docs/setup/configuring_build_options.rst @@ -269,6 +269,18 @@ Optimization You can make an optimized build with debugging symbols. See :ref:`Building with Debug Symbols `. +Building as Beta or Release +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``ac_add_options --as-milestone=release`` + This makes it easy to build nightly with a release or beta configuration to + test the different ifdef behaviors. To do a full beta simulation see + `Sheriffing/How To/Beta simulations `__. + + - ``early-beta`` + - ``late-beta`` + - ``release`` + Extensions ^^^^^^^^^^ -- cgit v1.2.3