summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 01:13:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 01:13:33 +0000
commit086c044dc34dfc0f74fbe41f4ecb402b2cd34884 (patch)
treea4f824bd33cb075dd5aa3eb5a0a94af221bbe83a /docs
parentAdding debian version 124.0.1-1. (diff)
downloadfirefox-086c044dc34dfc0f74fbe41f4ecb402b2cd34884.tar.xz
firefox-086c044dc34dfc0f74fbe41f4ecb402b2cd34884.zip
Merging upstream version 125.0.1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/bug-mgmt/processes/accessibility-review.md9
-rw-r--r--docs/code-quality/lint/create.rst4
-rw-r--r--docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/import-headjs-globals.rst1
-rw-r--r--docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/no-more-globals.rst20
-rw-r--r--docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-mixing-eager-and-lazy.rst11
-rw-r--r--docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/reject-relative-requires.rst2
-rw-r--r--docs/code-quality/lint/linters/eslint-plugin-mozilla/rules/valid-lazy.rst10
-rw-r--r--docs/code-quality/lint/linters/ignorefile.rst45
-rw-r--r--docs/conf.py1
-rw-r--r--docs/config.yml1
-rw-r--r--docs/contributing/index.rst8
-rw-r--r--docs/contributing/reviews.rst6
-rw-r--r--docs/contributing/signing/signing_macos_build.rst155
-rw-r--r--docs/setup/configuring_build_options.rst12
14 files changed, 271 insertions, 14 deletions
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) <tools/lint/ignorefile.yml>`
+* :searchfox:`Source <tools/lint/ignorefile/__init__.py>`
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
@@ -42,6 +42,14 @@ development process and source code documentation.
.. 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 <https://phabricator.services.mozilla.com/project/members/97/>`__
+ * - #android-reviewers
+ - Changes to Fenix, Focus and Android Components.
+ - `Member list <https://phabricator.services.mozilla.com/project/members/200/>`__
* - #geckoview-reviewers
- Changes to GeckoView
- `Member list <https://phabricator.services.mozilla.com/project/members/92/>`__
@@ -131,6 +134,9 @@ Review groups
* - #style or #firefox-style-system-reviewers
- Firefox style system (servo, layout/style).
- `Member list <https://phabricator.services.mozilla.com/project/members/90/>`__
+ * - #supply-chain-reviewers
+ - Changes to third-party audits and vendoring (cargo-vet, supply_chain).
+ - `Member list <https://phabricator.services.mozilla.com/project/members/164/>`__
* - #webcompat-reviewers
- System addons maintained by the Web Compatibility team
- `Member list <https://phabricator.services.mozilla.com/project/members/124/>`__
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 <path-to-dmg>
+ <drag Browser to the Desktop>
+ $ ./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 <path-to-dmg>
+ <drag Browser to the Desktop>
+ $ ./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 <https://bugzilla.mozilla.org/enter_bug.cgi?product=App%20Stores&component=App%20Store%20Access>`__
+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 <path-to-dmg>
+ <drag Browser to the Desktop>
+ $ ./mach macos-sign -a ~/Desktop/Nightly.app -s <MOZILLA_DEVELOPER_CERT_ID>
+
+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 <https://crates.io/crates/apple-codesign>`__ Using a pkcs12 Certificate Key Pair
+-----------------------------------------------------------------------------------------------------------------------------------------------
+
+More information about rcodesign can be found on the
+`rust crate page <https://crates.io/crates/apple-codesign>`__ or
+`github repo <https://github.com/indygreg/apple-platform-rs>`__. 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 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 <https://wiki.mozilla.org/Sheriffing/How_To/Beta_simulations>`__.
+
+ - ``early-beta``
+ - ``late-beta``
+ - ``release``
+
Extensions
^^^^^^^^^^