Skip to content

Latest commit

 

History

History
100 lines (73 loc) · 6.83 KB

CONTRIBUTING.md

File metadata and controls

100 lines (73 loc) · 6.83 KB
Raw

Contributing to jshiki

Thanks for the interest in contributing to jshiki! 🎉

This document goes over the process of contributing to jshiki and guidelines and tips on how to do so. Keep in mind that these are just guidelines and that not all contributions will always necessarily fit the mould — and that's okay! However, it would help if you always tried to follow these guidelines to the best of your ability.

Documentation | Issues | Pull Requests

Table of Contents

Workflow

Generally, the process of contributing to jshiki is as follows:

  1. Create a new issue on the issues page. If you're also submitting a pull request, include a link to the pull request in the issue.
    • For bugs: the issue should describe the bug, provide a code snippet that reproduces the bug, include what the expected and actual behaviour is, as well as any other relevant information.
    • For features: the issue should describe the feature and its use cases and the motivation for implementing it. It should also include a code snippet that demonstrates the desired behaviour and any other relevant information.
  2. Submit a pull request on the pull requests page.
    • Provide a link to the issue on the pull request.
    • Describe the changes you're making to the code.
    • If the changes are substantial, include a code snippet that demonstrates the desired behaviour and any other relevant information.
    • If the changes are breaking, make a note of that in the pull request.

Environment

  • Code is written in Typescript.
    • This package provides types for the jshiki library, so pay mind to the code you write and any changes to the types that a consumer of the package will use.
  • The package manager used is Yarn.
    • You can use npm if you prefer, but we only accept Yarn lock files into the repository, and all scripts should work when run using Yarn. Therefore, we recommend you use Yarn.
  • Tests are run using Jest.
    • See testing for more information.
  • Code is linted with ESLint and formatted with Prettier.
  • Documentation is generated using mkdocs and mkdocs-material, and API documentation is generated using typedoc. mike is used for versioning.

Testing

Any contributions to jshiki should be tested before being considered for inclusion in the main repository.

  • Contributions with new functionality should provide new tests.
  • Contributions that change existing functionality should also change any appropriate current tests and add new tests for cases that aren't covered by existing tests.
  • Contributions that fix bugs should also fix any appropriate existing tests.
  • All contributions should maintain:
    • 100% code coverage for unit tests
    • At least 90% and as much coverage as is reasonably possible for functional tests

The following scripts help to run tests:

  • yarn test: Runs all unit and functional tests.
  • yarn test:unit: Runs all unit tests and fails if coverage is below 100%. Coverage reports are generated in the coverage/unit directory.
  • yarn test:functional: Runs all functional tests and fails if coverage is below 90%, except for functions, which require 100% coverage. Coverage reports are generated in the coverage/functional directory.
  • yarn test-ci: Runs all unit and functional tests with coverage and generates separate reports for each. Unlike the test:* scripts, this script does not fail if coverage is below the required threshold.

Linting and Formatting

All code in jshiki should be linted and formatted with ESLint and Prettier. You can use the following scripts:

  • yarn lint: Lints all files in the repository using ESLint and Prettier and checks types using Typescript — in that order. It fails if it encounters any linting errors or type errors.
  • yarn format: Formats all files in the repository using ESLint and Prettier. Fails if ESLint finds any errors.

Make sure to lint and format your code before submitting a pull request. CI is configured to run these scripts automatically, failing the build if you miss a linting or formatting error.

Documentation

You should document any user-facing change in the user guide and in any related documentation comments on public API points. jshiki uses mkdocs and mkdocs-material to generate a static docs site using written documentation and typedoc to generate API documentation.

Documentation is stored in the docs directory, The user guide is kept in the docs/user-guide directory, and API documentation is generated in the docs/api directory.

mkdocs runs on Python, so you'll need to install Python and pip to generate documentation. Once you've installed Python and pip, you can run yarn install-docs-deps to install the necessary dependencies to generate documentation (this script runs pip install --upgrade -r requirements.txt).

Once you have installed all dependencies, you can use these scripts to generate the documentation site:

  • yarn build-docs: Builds documentation and API docs for development and outputs them to the site directory. Equivalent to running both of the following scripts in sequence:
    • yarn build-docs:api: Builds API documentation and outputs it to the docs/api directory.
    • yarn build-docs:docs: Builds user guide documentation and outputs it to the site directory, along with a copy of whatever API docs are in the docs/api directory.
  • yarn watch-docs: Watches code and the docs directory and rebuilds documentation and API docs when it detects changes. It serves the documentation at http://localhost:8000. Equivalent to running both of the following scripts in parallel:
    • yarn watch-docs:api: Watches code and rebuilds API docs in docs/api when it detects changes.
    • yarn watch-docs:docs: Watches the docs directory and rebuilds the documentation website in site when changes are detected.

Versioning is handled using mike; however, you don't need to run it manually. CI will build the documentation and run the versioning script for you once the code is committed to the main branch and when a new release is cut.