Publishing and Releases

Language: English · فارسی

Publishing and releases

Cutting a release

1. Update CHANGELOG.md — move Unreleased items under the new version

2. Bump version in package.json

3. npm run verify

4. Commit, tag, push:

   git commit -am "chore(release): v0.1.0"
   git tag v0.1.0
   git push origin main --tags

The Release workflow then verifies the tree, checks the tag matches package.json, builds both targets, and attaches to a GitHub release:

bale-privacy-<version>-chrome.zip
bale-privacy-<version>-firefox.zip
bale-privacy-source.zip          # for Mozilla's source-code review

Store uploads only run when the matching repository secrets exist, so the workflow is safe to run before any store account is set up.

Chrome Web Store

Everything the dashboard asks for is pre-written in CHROMEWEBSTORE.md — listing copy, category, single purpose, permission justifications and the data-use answers. Copy from there rather than improvising at submission time.

Short version:

1. Register a developer account (one-off 5 USD fee) at https://chrome.google.com/webstore/devconsole
2. New item → upload bale-privacy-<version>-chrome.zip
3. Fill in the listing from CHROMEWEBSTORE.md; upload the screenshots in site/assets/ (1280×800)
4. Privacy policy URL: https://amiranmanesh.github.io/bale-privacy-extension/privacy.html
5. Data use: does not collect user data, and tick the three certifications
6. Submit. Review usually takes a few days.

Automating later releases

Add these repository secrets and the Release workflow uploads on every tag: CHROME_EXTENSION_ID, CHROME_CLIENT_ID, CHROME_CLIENT_SECRET, CHROME_REFRESH_TOKEN.

Firefox Add-ons (AMO) — published

Live: https://addons.mozilla.org/firefox/addon/privacy-for-bale-web/

The add-on id {9699286f-8a2b-4bf9-94fa-f3b8aedb9814} is pinned in scripts/manifest.mjs and must never change: it is what ties every future upload to this listing instead of creating a second one.

Automatic uploads

Pushing a v* tag runs the release workflow, which builds the package, attaches it to the GitHub release, then signs and uploads it to AMO. It first asks AMO which version is live and skips the upload if that version is already there, so re-running a release is safe.

Two repository secrets switch it on, both generated at https://addons.mozilla.org/developers/addon/api/key/:

Secret	Value
AMO_JWT_ISSUER	JWT issuer, looks like user:12345678:123
AMO_JWT_SECRET	JWT secret — shown once, regenerate if lost

Add them under Settings → Secrets and variables → Actions → New repository secret. Until they exist the step is skipped and the release still succeeds.

The upload includes bale-privacy-source.zip, which AMO requires because the shipped bundles are minified by esbuild.

What stays manual

web-ext sign uploads the package only. The listing text, screenshots, categories and privacy policy are edited in the Developer Hub; the copy to paste lives in AMO.md.

Manual upload

npm run verify && npm run package
npx web-ext sign --source-dir dist/firefox --channel listed \
  --upload-source-code release/bale-privacy-source.zip \
  --api-key "$AMO_JWT_ISSUER" --api-secret "$AMO_JWT_SECRET"

Build instructions for a reviewer, if asked:

Requirements: Node 22 (see .nvmrc), npm.
Build:  npm ci && npm run build:firefox
Output: dist/firefox/ — identical to the submitted package.

Other Chromium stores

The same dist/chrome package works for Microsoft Edge Add-ons (https://partner.microsoft.com/dashboard/microsoftedge) and Opera. Both accept an unmodified Manifest V3 zip.

Naming and trademarks

• "for Bale Web" is a descriptive reference, never a claim of origin; never put "Bale" first in a way that reads like an official app
• No Bale logo, wordmark, colours or branded screenshots — the icon and every published screenshot in this project are original, and the screenshots use fabricated data
• Keep the disclaimer visible in the listing, the README, the site and the options page: Independent open-source project. Not affiliated with, endorsed by, or connected to Bale.