CONTRIBUTING.md

Contributing

Setup development prerequisites

• Create a Firefox Add-ons (AMO) account
• Install followings:
  • WebExtensions enabled Firefox
  • Node.js v16 or later. Package scripts need npm@7.
  • Python 2.x for compiling dtrace-provider (web-ext requires this as dependency)

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 but you don't have to update package.json nor manifest.json as I will maintain release.

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

   $ npm install

4. Create a new topic branch

   $ git checkout -b add-new-feature

5. Run js bundler/watcher and firefox

   $ npm run watch

6. Modify source code and firefox will reload the extension automatically

Testing

1. Run test cases

   $ npm 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 test.js

   turndownService.use(turndownPluginMathJax);

2. Update Jest snapshot

   $ npm run test:core -- --updateSnapshot

3. Revert test.js
4. Run test cases

   $ npm 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.

References

Package Scripts

Run with npm run <script-name>.

• Watchers
  • watch: Run watch scripts
• Builds
  • build: Build the extension with webpack
  • generate: Generate WebExtension artifacts
  • format: format JS files by Prettier

Mozilla Developer Network (MDN)

• Browser Extensions
• Getting started with web-ext
• Signing and distributing your add-on