Contributing

August 12, 2026 ยท View on GitHub

Setup development prerequisites

Fork on GitHub

Before you do anything else, login on GitHub and fork this repository

Clone your fork locally

Install Git and clone your forked repository locally.

$ git clone https://github.com/<your-account>/copy-selection-as-markdown.git

Play with your fork

The project uses Semantic Versioning 2.0.0 and is organized as a monorepo with packages in packages/. You don't have to update version numbers in package.json files as releases are maintained centrally.

  1. Open your terminal, navigate to local repository directory
  2. Export AMO's API key and secret as environment variable 
    $ export WEB_EXT_API_KEY=...
$ export WEB_EXT_API_SECRET=...
  3. Install dependencies 
    $ pnpm install
  4. Create a new topic branch 
    $ git checkout -b add-new-feature
  5. Run js bundler/watcher and firefox 
    $ pnpm run watch
  6. Modify source code and firefox will reload the extension automatically

Publishing to Firefox Add-ons

Pushing a version tag publishes the Firefox extension to the existing public listing on addons.mozilla.org. Before tagging, update the version in the root package, every workspace package, and both browser manifests. All versions must match the tag without its v prefix.

The repository must define these GitHub Actions secrets:

  • WEB_EXT_API_KEY: the AMO API JWT issuer
  • WEB_EXT_API_SECRET: the AMO API JWT secret

Create the credentials on the AMO API key page. To publish version 0.24.0, push tag v0.24.0:

$ git tag v0.24.0
$ git push origin v0.24.0

The workflow verifies the versions, runs the checks and tests, builds the extension and reviewer source archive, then submits the extension to AMO's listed channel. AMO review and approval may complete after the workflow.

Testing

  1. Run test cases 
    $ pnpm test

To make sure Turndown conversion remains intact after my modification for supporting MathJax, I use Jest snapshot testing. When you updated Turndown, you have to update snapshots.

  1. Comment out following line from packages/core/test/test.js 
    turndownService.use(turndownPluginMathJax);
  2. Update Jest snapshot 
    $ pnpm --filter copy-selection-as-markdown-core test -- --updateSnapshot
  3. Revert packages/core/test/test.js
  4. Run test cases 
    $ pnpm test

Open a pull request

  1. Commit your changes locally, rebase onto upstream/master, then push the changes to GitHub 
    $ git push origin add-new-feature
  2. Go to your fork on GitHub, switch to your topic branch, then click "Compare and pull request" button.

Project Structure

This project is organized as a monorepo with the following packages:

  • packages/core/ - Core functionality and markdown conversion logic
  • packages/firefox/ - Firefox-specific extension code and manifest
  • packages/chromium/ - Chromium-specific extension code and manifest

Each package has its own package.json with specific dependencies and build scripts. The root package.json orchestrates builds across all packages using pnpm workspaces.

References

Package Scripts

Run with pnpm run <script-name> from the project root.

  • Watchers
    • watch: Run watch scripts for all packages
    • watch:core: Watch core package only
    • watch:firefox: Watch Firefox package only
  • Builds
    • build: Build all packages (core, firefox, chromium)
    • generate: Generate WebExtension artifacts
    • format: Format JS files with Biome
  • Testing
    • test: Run tests across all packages
  • Maintenance
    • clean: Clean all build artifacts

Mozilla Developer Network (MDN)