Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
81 lines (50 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

81 lines (50 loc) · 4.17 KB

Contributing to Saladict

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

How to Contribute

⚠️ Unless it is a small hot fix, before you write any code and get your hands dirty, please open an issue or make a WIP pull request to elaborate what you are trying to do and how you are going to implement it. Just to make sure we are on the same page and nobody's time and effort are wasted.

How to get started

Clone the repo and run yarn install.

UI Tweaking

Run yarn storybook to view all the components.

Run yarn start --wextentry [entry id] to view a certain entry with WDS in a fake WebExtension environment.

Testing

Run yarn test to run Jest. Supports all the Jest options.

Building

Run yarn build to start a full build.

Toggle:

  • --analyze: Show detailed Webpack bundle analyzer.

Releasing

Run yarn release to bump version and generate CHANGELOG.

Zipball

Run yarn zip to pack zibballs to ./dist/.

How to add a dictionary

  1. Create a directory at src/components/dictionaries/, with the name of the dict ID.
    1. Use any existing dictionary as guidance, e.g. Bing. Copy files to the new directory.
    2. Replace the favicon with a new LOGO.
    3. Edit config.ts to change default options. See the DictItem type and explanation for more details. Register the dictionary in app config so that TypeScript generates the correct typings. Dict ID MUST follow alphabetical order.
    4. Update _locales.json with the new dictionary name. Add locales for options, if any.
    5. engine.ts MUST export at least two functions:
      1. getSrcPage function which is responsible for generating source page url base on search text and app config. Source page url is opened when user clicks the dictionary title.
      2. search function which is responsible for fetching, parsing and returning dictionary results. See the typings for more detail.
        • Extracting information from a webpage MUST use helper functions in ../helpers.ts for data cleansing.
        • If the dictionary supports pronunciation:
        1. Register the ID at config.autopron.
        2. Include an audio field in the object which search engine returns.
      3. Other exported functions can be called from View.tsx via DictEngineMethod message channel, see src/typings/message for typing details (also don't use the native sendMessage function, import { message } from '@/_helpers/browser-api').
    6. Search result will ultimately be passed to a React PureComponent in View.tsx, which SHOULD be a dumb component that renders the result accordingly.
    7. Scope the styles in _style.scss following ECSS-ish naming convention.

Add Testing

  1. Add response samples at test/specs/components/dictionaries/[dictID]/response.
  2. Add engine.spec.ts to test the engine.

Develop the dictionary UI live

  1. Edit test/specs/components/dictionaries/[dictID]/request.mock.ts.
  2. Run yarn storybook.

Code Style

This project follows the TypeScript variation of Standard JavaScript code style.

If you are using IDEs like VSCode, make sure TSLint related plugins are installed. Or you can just run building command to perform a TypeScript full check.

Commit Style

This project follows conventional commit style.

You can run yarn commit and follow the instructions, or use vscode-commitizen extension in VSCode.