Skip to content

Latest commit

 

History

History
97 lines (65 loc) · 12.3 KB

RELEASING.md

File metadata and controls

97 lines (65 loc) · 12.3 KB

Releasing Module Engine

How a version is packaged and how installed copies then update themselves. Every step here runs offline except the uploads, which need the publisher's own accounts; scripts/package-extension.cjs never signs, uploads or contacts anything.

Development · Verification · README

How installed copies update

Browser How people install it How it updates
Chrome Chrome Web Store listing The store updates installed copies after each accepted upload.
Microsoft Edge Microsoft Edge Add-ons listing The same, through Edge Add-ons.
Firefox (public listing) Firefox Add-ons (AMO) Mozilla hosts and updates accepted versions. Build without --firefox-update-url.
Firefox (self-distribution) A Mozilla-signed package from the project's releases Firefox checks the package's update_url and installs a higher signed version.
Any Unpacked or temporary source install (development) Never: reload the folder by hand.

Chrome and Edge on Windows and macOS install extensions only from their stores, apart from enterprise policy, so a self-hosted Chrome package cannot update ordinary installs. Firefox allows self-distribution, but only of packages Mozilla has signed.

Inside every install, the filter lists (EasyList and EasyList China) update themselves from their publishers. The reported-threat list can update itself from the project folder once src/shared/update-config.js names one; see Development.

Before the first public release

These are the publisher's decisions; nothing in the code makes them.

  • Licence. Module Engine's own source is MIT (LICENSE). Bundled lists and vendored code keep their own licences, listed in the README; store listings that ask for a licence take MIT for the extension.
  • Firefox add-on ID. The manifest's browser_specific_settings.gecko.id is blockads-shield@local.extension, from the old name. Mozilla ties every signed version to this ID, and an installed copy only takes updates with the same ID. Choose the permanent ID before the first signed package, for example one based on the project's domain or repository.
  • Store accounts and listing details. These are a Chrome Web Store developer account, a Microsoft Partner Center account for Edge and an addons.mozilla.org account for Firefox signing. Stores ask for a privacy disclosure and a reason for each permission in the uploaded manifest, including <all_urls>, scripting, webRequest and the optional userScripts. Permissions describes what each is for.
  • Update addresses. A public Firefox listing needs no custom extension update address. For self-distribution, serve the Firefox update manifest from the project, for example https://raw.githubusercontent.com/<owner>/Module-Engine/main/updates/firefox/updates.json. Reported-threat updates have their own independently configured address.
  • Firefox data disclosure. The manifest declares no required data collection. The optional MCP connection can send browsing activity, script/request information and technical diagnostics to the user's selected local client, which may forward them to its AI service. The Firefox package requires Firefox 142+ and asks for the three optional data permissions before connecting; denial, Disconnect, page unload or permission revocation prevents further sharing. This is not project telemetry. Installed userscripts have their own reviewed grants and can transmit data according to their code. See Mozilla's data-consent requirements and MCP.

Each release

  1. Version. node scripts/package-extension.cjs version 1.10.0 raises manifest.json's version; every store and Firefox need a higher version than the last. Rebuild the rules first if the bundled lists or catalogs changed (see Development).

  2. Tests. Run the Node and PowerShell suites from the README and the browser suites in Verification. Then run node tests/package-browser.cjs chrome, edge and firefox --listed, which load the built packages themselves. Omit --listed to test the self-distributed Firefox update configuration.

  3. Packages.

    node scripts/package-extension.cjs build

    This writes these files to dist/:

    • module-engine-<version>-chromium.zip, for both Chrome and Edge;
    • module-engine-<version>-firefox.zip;
    • SHA256SUMS.

    Both archives hold exactly the files the browser tests load, listed in scripts/extension-files.cjs. Each manifest drops the other browser's keys. The Chromium store manifest also removes declarativeNetRequestFeedback (used here only for unpacked debug events) and webRequestBlocking (used only by the Firefox helpers). The Firefox manifest removes Chromium's offscreen permission. The source manifest retains these permissions for Firefox and unpacked development. The same source gives byte-identical archives. Local worktrees, .artifacts, tests and verification history are excluded. manifest.json is at the archive root, as Mozilla requires.

  4. Chrome and Edge. Upload the Chromium archive in the Chrome Web Store Developer Dashboard and in Microsoft Partner Center. After review, the stores update installed copies.

  5. Firefox public listing. In the Mozilla Add-ons Developer Hub, choose On this site and upload module-engine-<version>-firefox.zip. Select desktop platforms; Android has not been validated. Mozilla performs server validation, review and signing. The local ZIP is unsigned, and local tests are not an AMO approval. Upload the corresponding reviewer source archive when asked; generated rules and styles can be rebuilt from its bundled inputs. Accepted public versions use Mozilla's update service.

  6. Firefox self-distribution (alternative). Build into a separate output directory with --firefox-update-url https://raw.githubusercontent.com/<owner>/Module-Engine/main/updates/firefox/updates.json. Choose On your own at the Developer Hub. After signing completes, download the signed XPI. Obtain the file.hash for that signed version independently from your authenticated Mozilla Add-ons version record. Copy Mozilla's full sha256:… value into the command below. A hash computed from the candidate XPI itself provides no independent check. Mozilla version detail API

    node scripts/package-extension.cjs firefox-update --xpi module-engine-1.10.0-firefox.xpi --amo-hash sha256:<digest-from-mozilla> --link https://github.com/<owner>/Module-Engine/releases/download/v1.10.0/module-engine-1.10.0-firefox.xpi

    The helper checks the exact archive bytes against Mozilla's digest before reading the package or writing updates/firefox/updates.json. It also checks the signature filenames, add-on ID and update address. Firefox performs the cryptographic signature verification at installation. Attach the verified XPI to the release, then publish the updated manifest.

The command-line alternative to the Developer Hub upload is Mozilla's web-ext sign, which needs a separate install and the publisher's API keys.

Reviewer source archive

Commit the release changes before archiving so the source matches the upload. Replace 1.9.0 with the release's actual version:

git archive --format=zip --output=dist/module-engine-1.9.0-source.zip HEAD LICENSE PRIVACY.md README.md manifest.json src icons lists rules vendor scripts docs tests mcp development

Extract the source, then run node scripts/package-extension.cjs build from its root to reproduce the upload. No npm packages, downloads or bundler are required; Node 22+ is used. JavaScript is shipped readable. Included prebuilt rule files are also reproducible offline with PowerShell 7+: pwsh -NoProfile -File scripts/build-rules.ps1, followed by the same packaging command. The list inputs, catalogs, compiler scripts and third-party provenance/licences are included. See Development and Mozilla's source-submission guide.

AMO version notes for 1.9.0

Copy the following into the version notes:

Module Engine 1.9.0 provides local ad and tracker blocking, custom network and page-hiding filters, and an optional userscript manager with explicit site scopes and permissions.

- Bundled EasyList, EasyList China and uBlock filters provide the starting filter data. EasyList and EasyList China can update from their publishers; uBlock filters update with extension releases.
- Userscripts can be created, imported and reviewed before enabling. The manager supports local script values, cached dependencies, tags, ordering and reviewed access changes during updates.
- Backup & restore exports settings, custom filters, appearance, scripts, values and prepared dependencies to a local JSON file. Restore previews the replacement and leaves restored scripts disabled until reviewed and enabled again.
- Optional local MCP debugging shares only approved scopes with the selected client. Firefox data-sharing permission is requested before connecting and revocation disconnects the session.
- The Firefox release requires Firefox 142 or later and omits Chromium-only offscreen permission. Chrome and Edge requirements remain unchanged.

AMO notes to reviewer for 1.9.0

Copy the following into Notes to Reviewer. Upload the matching source ZIP in the source-code step.

No website account, subscription, test username or password is required. Please test on desktop Firefox 142 or later; Android has not been validated and is not included in the intended release platforms.

Open the toolbar popup or the add-on's options page. Ad blocking and userscripts have separate switches. The userscript module starts disabled. To test it, open Modules & scripts, choose Allow userscript access and approve Firefox's prompt, enable the module, then create or import a script with an explicit site match. Review and save it, enable Run this script, and reload a matching ordinary HTTP(S) page. Browser-restricted pages are not script targets. Saving an edit pauses that script again. Optional clipboard, notification, download, cookie and network helper access depends on the script's declared grants and separate browser approval.

To test Backup & restore, download a backup, change a saved setting, select the backup and inspect the preview, then acknowledge and choose Replace and restore. This replaces saved settings and the script library. Restored scripts and their module remain disabled. Backups are local, unencrypted JSON; they are not sent to a server and do not include browser permissions or MCP connection approvals.

The extension has no project telemetry or required data collection. Filter updates download lists from their publishers. User-installed scripts may access their matched pages and transmit data according to their source and granted access. Optional MCP debugging connects only after in-page approval and Firefox's optional data-consent prompt. It sends the selected status, script information and diagnostic/request metadata to the user's local MCP client, which may forward it to its configured AI service. No AI account is required for the blocker or userscript manager. MCP is off unless explicitly paired; source ZIP docs/MCP.md explains the optional Node-based server and client setup.

The matching source ZIP contains readable JavaScript, bundled rule inputs, compiler scripts and third-party licences/provenance. From its extracted root, run node scripts/package-extension.cjs build using Node 22+; no npm install or network download is needed. To regenerate the bundled rules first, run pwsh -NoProfile -File scripts/build-rules.ps1 with PowerShell 7+, then the packaging command. The Firefox upload is dist/module-engine-1.9.0-firefox.zip. Build and testing details are in docs/RELEASING.md, docs/DEVELOPMENT.md and docs/VERIFICATION.md.