anton.galiglobal.com
Firefox WebExtension (Desktop and Mobile) that lets you share the current tab to Margit.at, frontpage.fyi, etc. with minimal effort.
1# Contributing to ATProto Social
2
3## Development install (temporary)
4
51. Open `about:debugging#/runtime/this-firefox`.
62. Click **Load Temporary Add-on…** and choose `manifest.json` inside the
7 `extension/` directory.
83. Pin the "ATProto Social" toolbar button if you want quick access.
9
10> This method is ideal while iterating; Firefox forgets the add-on on restart.
11
12## Development tips
13
14- Inspect background/service-worker logs from `about:debugging` → **Inspect**.
15- The UI scripts (`popup.js` and `options.js`) log to the DevTools console
16 attached to their respective documents.
17- When packaging for distribution, zip the contents of the `extension/`
18 directory (see workflow below).
19- Licensed under the [Apache License 2.0](./LICENSE).
20
21## Implementation notes
22
23- The background worker discovers the user's PDS by resolving the handle
24 (`com.atproto.identity.resolveHandle` + PLC lookup).
25- Sessions are refreshed automatically via `com.atproto.server.refreshSession`
26 when the access JWT expires.
27- All data stays in `browser.storage.local`; nothing is transmitted to
28 third-party services beyond the ATProto endpoints.
29- Margin records use the `at.margin.annotation` and `at.margin.highlight`
30 lexicons with a `TextQuoteSelector` for text targeting.
31- Maximum lengths follow the current Frontpage limits (120 characters for the
32 title, 2048 for URLs).
33
34## Cutting a release
35
36Mozilla requires every signed upload to have a unique version number, so the
37first step is always bumping the version.
38
39**1. Bump the version in `extension/manifest.json`:**
40
41```json
42"version": "0.1.7"
43```
44
45**2. Commit and push to `main`:**
46
47```sh
48git add extension/manifest.json
49git commit -m "Bump version to 0.1.7"
50git push
51```
52
53**3. Trigger the `package-extension` workflow:**
54
55Via the GitHub UI (`Actions` → **package-extension** → **Run workflow**), or
56with the `gh` CLI:
57
58```sh
59gh workflow run package-extension.yml --repo antonmry/atproto_firefox_plugin
60```
61
62**4. Monitor the run:**
63
64```sh
65gh run list --workflow=package-extension.yml --repo antonmry/atproto_firefox_plugin
66gh run watch --repo antonmry/atproto_firefox_plugin
67```
68
69**5. Check the resulting release:**
70
71```sh
72gh release list --repo antonmry/atproto_firefox_plugin
73gh release view --repo antonmry/atproto_firefox_plugin
74```
75
76The workflow publishes a GitHub Release tagged `v<version>-<run-id>` with the
77signed `.xpi` (when `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` secrets are set) and
78an unsigned `.zip`. These artifacts can be hosted directly for self-distribution
79as described in the
80[Mozilla documentation](https://extensionworkshop.com/documentation/publish/self-distribution/).
81
82## Tangled mirror
83
84The `mirror-to-tangled.yml` workflow pushes every commit on `main` to Tangled, a
85federated Git hosting platform built on ATProto. Browse the mirror at
86<https://tangled.org/anton.galiglobal.com/frontpage_firefox_plugin>. Add a
87deploy key with write access as the `TANGLED_DEPLOY_KEY` repository secret so
88the mirror stays up to date.