Releasing

Releasing

This page is for people who release Preen. Questions go to the issue tracker. It describes what the repository does for version 0.0.29.

Checklist

1. Bump the version in these places. They must agree:
   • apps/thunderbird/manifest.json (version)
   • package.json (version)
   • the <meta name="preen-version"> tag in each page: apps/thunderbird/ui/options/options.html, apps/thunderbird/ui/popup/popup.html, apps/thunderbird/ui/activity/activity.html, apps/thunderbird/ui/confirm/confirm.html
   • the status line in README.md, and the .xpi name in its "Get started" steps
2. Add a section to apps/thunderbird/CHANGELOG.md for the new version. The root CHANGELOG.md only links to each app's changelog.
3. Run the tests with npm test. They must all pass. One test checks that every page's version tag matches the manifest.
4. Merge to main. The release workflow refuses a tag that is not on main.
5. Tag it. Tags are per app and named <app>-v<version>. For Thunderbird the tag is thunderbird-v<version>, such as thunderbird-v0.0.25. It must match apps/thunderbird/manifest.json. The older tags v0.0.22 to v0.0.24 are earlier Thunderbird releases and stay as they are.
6. Push the tag. This starts the Release workflow.

Tags and labels for each app

Each app has its own tag prefix and its own version numbers, so a release of one app never changes another.

App	Tag	Status
Thunderbird	thunderbird-vX.Y.Z	In use
Betterbird	none, it uses the Thunderbird release	Planned
SeaMonkey	seamonkey-vX.Y.Z	Reserved
Outlook	outlook-vX.Y.Z	Reserved
KMail	kmail-vX.Y.Z	Reserved
Claws Mail	claws-mail-vX.Y.Z	Reserved
Evolution	evolution-vX.Y.Z	Reserved
Gmail (Google Workspace add-on)	gmail-vX.Y.Z	Reserved
Apple Mail (macOS)	apple-mail-vX.Y.Z	Reserved

• Betterbird runs Thunderbird add-ons, so it gets no build of its own unless one is needed. It would then use betterbird-vX.Y.Z.
• Today only Thunderbird has a release workflow (release.yml). When another app first ships, it adds its own .github/workflows/release-<app>.yml that runs on its prefix.
• GitHub marks only one release as "Latest" for the whole repository, so link to each app's newest release directly.
• Issues and pull requests use one label per app (app:thunderbird, app:outlook and so on) plus shared for packages/shared. The list, with colours, is .github/labels.json.

What the Release workflow does

It runs on any pushed tag that starts with thunderbird-v in .github/workflows/release.yml:

flowchart TD
  A["Tag thunderbird-v* pushed"] --> B["Check out full history"]
  B --> C{"Is the tagged commit on origin/main?"}
  C -->|"no"| X["Fail"]
  C -->|"yes"| D{"Does the tag match<br/>the manifest version?"}
  D -->|"no"| X
  D -->|"yes"| E["npm test"]
  E --> F["build and sh scripts/package.sh<br/>key scan + zip"]
  F --> G["gh release create<br/>attach the .xpi, generated notes"]

Loading

1. Checks the tagged commit is an ancestor of origin/main.
2. Checks the tag name equals thunderbird-v plus the version in apps/thunderbird/manifest.json.
3. Runs npm test.
4. Builds dist/thunderbird/ and runs sh scripts/package.sh. The build removes hidden files and folders. The script stops if the build has anything that looks like a key, matching sk-or-v1-..., sk-..., BEGIN ... PRIVATE KEY and Bearer ... tokens.
5. Creates a GitHub Release titled Preen for Thunderbird <version>, attaches preen-thunderbird-<version>.xpi and generates the notes with --generate-notes.

The workflow needs contents: write. It uses the built-in GITHUB_TOKEN.

CI

.github/workflows/ci.yml runs npm test on pushes to main, on pull requests and on manual dispatch. Node comes from .nvmrc.

ATN (Thunderbird Add-ons)

ATN is the recommended way to install Preen. The listing is not live yet.

The manifest already declares sensitiveDataUpload and data_collection_permissions, with personalCommunications and personallyIdentifyingInfo as required. Version 0.0.24 added the permission because ATN requires it for add-ons that send mail content to a third party.

Debug submissions and usage statistics

Version 0.0.29 sends neither. TELEMETRY_URL in packages/shared/core/telemetry.js and SUBMIT_URL in packages/shared/core/debug.js are empty, the manifest declares no host permission for them, and the settings page has no controls for usage statistics. While SUBMIT_URL is empty, the debug submission dialog offers only "Save as file".

To turn them on, a release would need to:

1. Set TELEMETRY_URL and SUBMIT_URL to the HTTPS addresses of a server.
2. Add both addresses to host_permissions in apps/thunderbird/manifest.json.
3. Update PRIVACY.md with the addresses and how the server handles the data.
4. Update the ATN listing text and the Settings and Privacy-and-Data wiki pages, which now say nothing is sent.
5. Run npm test. The tests check that nothing is fetched while a URL is empty.

Updates for the GitHub .xpi

The GitHub .xpi has no update URL, so it does not update itself. A design for self-updating builds exists but is not built, and nothing in Preen depends on it.

Publishing the wiki

The wiki is its own git repository, Preen-AI-email-sorting.wiki.git. Copy the wiki files in, including images/, and push. Do not copy files that start with an underscore and end in .json, such as _option_inventory.json, which is a draft-only file. Keep _Sidebar.md and _Footer.md.