Hi!
Thank you so much for offering to contribute! Here are a few tips that might help.
-
Quality over features. Your code doesn't need to be great (we'll work on it together) but we're generally more interested in fixing the basics (faster, more robust, more accurate lookups etc.) than adding half-baked features. When we add a feature, we like to do it properly.
-
Options are a refuge for the indecisive 😅. It's tempting to hedge your bets and "just add an option" but we try to avoid that when possible. It makes the extension harder to maintain and most users will never discover the option. Instead it's worth working out if there's a different approach that will work well for (nearly) everyone. So far we've been pretty successful at doing that.
-
Wrap extended commit messages to 80 characters. The first-line summary may be longer.
If you have the gh CLI tool installed,
you can fork and clone in one command:
gh repo fork birchill/10ten-ja-reader --clone=true
However, because we store snapshots of the dictionary data in the repository, it might take a while so you might prefer a blobless clone:
gh repo fork birchill/10ten-ja-reader
git clone --filter=blob:none birchill/10ten-ja-reader
Then install the dependencies:
pnpm install
To build the Firefox version:
pnpm build:firefox
The output should be in the dist-firefox folder.
Similarly you can use pnpm build:chrome, pnpm build:edge, pnpm build:thunderbird to build the Chrome, Edge, and Thunderbird versions.
The output will be in the dist-chrome, dist-edge, dist-thunderbird folders
respectively.
To build and package up a zip:
pnpm package:firefox # or pnpm package:chrome, pnpm package:edge etc.
First run:
pnpm build:safari
Then open Xcode and choose the .xcodeproj under xcode13.
You will need to select the target platform (iOS vs Mac) to build.
For manual testing you can use:
pnpm start:firefox # or pnpm start:chrome
This will run the app using the rspack runner in Firefox (or Chrome) with automatic reloading.
To run a specific version of Firefox:
pnpm start:firefox --env firefox=nightly
Other options include:
--env firefoxProfile=<path>,--env chromium=<path>,--env chromeProfile=<path>,--env keepProfileChanges, and--env profileCreateIfMissing.
(I believe the latter two options only apply to Firefox.)
Instructions are here.
Once you've set up adb correctly and got the device ID, you should be able to run:
pnpm web-ext run -t firefox-android --adb-device <device ID> --firefox-apk org.mozilla.fenix
That will use the version of web-ext installed by this project.
As with the build instructions above, after running pnpm build:safari you
should be able to run using Xcode.
Note that Xcode will default to signing Debug builds with the Birchill, Inc. team. If you want to run and debug the Safari app or extension locally, you may need to override the team to your own personal team in Xcode. Please don't commit the resulting project file changes back to this repo. This is clunky, but unavoidable for open source projects that need Xcode signing in order to run locally. An Apple Developer Program account may also be required.
If you already have 10ten Japanese Reader installed on your device, you may get signing errors when trying to test the development version. An uninstall and reinstall should fix these.
If you want to test the extension in a state more like what will get shipped to users, you can use the "Create Safari Test Build" workflow to trigger a build that will get uploaded to App Store Connect where it can be tested via TestFlight.
However, the build will currently only be available to internal testers, i.e. Birchill team members so it's probably not very useful.
pnpm test
Unit tests only:
pnpm test:unit
Browser-based tests only:
pnpm test:firefox
pnpm test:chrome
Running a single browser-based test in watch mode:
pnpm test:firefox src/content/get-text.browser.test.ts --watch
For debugging a test, you may want to turn off headless mode:
pnpm test:firefox src/content/get-text.browser.test.ts --browser.headless=false
To debug with Chrome, you can add a debugger statement and run with:
pnpm test:chrome src/content/get-text.browser.test.ts --browser.headless=false --inspect-brk --no-file-parallelism
That will start the test initially paused and you'll need to open DevTools and resume before hitting your actual breakpoint.
We use Changesets to collect release notes and bump the extension version.
For user-visible changes, run:
pnpm changeset
Choose the bump type and write the release note text there instead of editing
CHANGELOG.md directly. If a note only applies to specific release targets,
start the item with the existing target annotation style, e.g. (Firefox) or
(Chrome, Edge). Bare issue references such as #123 are linked when
Changesets updates the changelog.
These target annotations also decide which stores a release is published to. An
unannotated note applies to every browser, so a browser is only skipped if
every note in the release excludes it. To cut a Firefox-only release, for
example, annotate every note with (Firefox); the other stores then have no
applicable notes and are skipped automatically, and the changelog heading is
stamped with a matching (Firefox only) annotation for the historical record.
(Note that the Safari/iOS build is always uploaded to App Store Connect regardless of these annotations—uploading a build there does not oblige us to actually submit it for release—and Thunderbird is published manually.)
Pre-release checks:
-
If we've made changes to the build setup at all, it's good to run
pnpm zip-srcand verify that the generated zip file can actually be used to build the add-on for Firefox.e.g.
pnpm zip-src mkdir ~/test-src cp dist-src/10ten-ja-reader-<version>-src.zip ~/test-src/test.zip cd ~/test-src unzip test.zip # Check it builds pnpm install pnpm build:firefox # Check it runs pnpm start:firefox # Clean up cd .. rm -rf ~/test-srcOtherwise the submission will likely be rejected from AMO.
-
It's also good to check that the release notes are being parsed correctly by running
pnpm tsx scripts/release-notes.js.
When changesets are merged to main, the
Changesets workflow
creates or updates a release PR. That PR contains the computed version bump,
the generated changelog, synced manifest/Xcode marketing versions, and a preview
comment showing both the GitHub release notes and the store-submission notes.
Until release, the new version's changelog heading stays in its plain
## <version> form (this is what lets the Changesets action show just the new
section in the release PR body). Merge the release PR when you are ready to
release. The
Release workflow
then updates the dictionary snapshot, stamps the release date (and, for a
browser-restricted release, a (… only) annotation) onto the changelog heading
(## [<version>] - <date>), builds the release assets from that updated commit,
tags it, and creates a draft GitHub release that you need to publish before
anything gets uploaded.
If you need to test the versioning process locally, use a temporary branch and run:
pnpm changeset-version
That command rewrites tracked release files such as CHANGELOG.md,
manifest.json.src, and the Xcode marketing version, so do not run it on a
working branch unless you intend to create the release PR contents yourself.
After publishing the release, it should automatically be uploaded to AMO (Firefox), the Edge Store, and the Chrome Web Store but we need to manually upload it to the Thunderbird add-ons site.
The release process will automatically upload the Mac and iOS packages to App Store Connect where they will be processed.
From there, Birchill team members can test them out with TestFlight if necessary.
In order to actually ship a new version though, we currently need to log in to App Store Connect:
- Go to https://appstoreconnect.apple.com/apps and choose 10ten Japanese Reader
- Choose the MacOS/iOS app and copy the Promotional Text.
- Press the blue + next to the macOS/iOS App and enter the new version number
- Fill out the changes field / promotional text and save (If it ever fails to save because, e.g. you entered a disallowed character, you lose all your work so save regularly.)
- Select the uploaded build. It can take a few minutes to be processed after which you'll need to reload the page to see it. You can check the status of processing the build from the TestFlight tab.
After that is done, you'll need to do the same for the iOS/MacOS build depending on which one you did first.