Skip to content

Latest commit

 

History

History
137 lines (102 loc) · 5.45 KB

CONTRIBUTING.md

File metadata and controls

137 lines (102 loc) · 5.45 KB
Raw

Contributing to rich-text

PRs Welcome   Semantic Release   JS Standard Style

We appreciate any community contributions to this project, whether in the form of issues or pull requests.

This document outlines what we'd like you to follow in terms of commit messages and code style.

It also explains what to do if you want to set up the project locally and run tests.

Working on your first Pull Request? You can learn how from this free series: How to Contribute to an Open Source Project on GitHub

Useful npm scripts

  • npm run build builds vendored files in the dist directory of each package
  • npm run commit runs git commits with commitizen
  • npm run clean removes any built files and node_modules
  • npm run lint runs our TypeScript linter on all .ts files in each package
  • npm run test runs unit tests for all packages
  • npm run test:ci runs unit tests in CI mode (same as would be run by Travis)
  • npm run test:watch runs unit tests in "watch" mode (will refresh relevant code paths on save)

Setup

This project is a Lerna monorepo with several packages, each published separately to npm.

Local Development

Run npm install to install all necessary dependencies.

As a post-install step, all Lerna dependencies are hoisted, and hence internally reliant packages (e.g., rich-text-html-renderer, which depends upon rich-text-types) will resolve their modules via symlink. In other words, npm install will both install external dependencies for each project, and ensure packages that pull in other packages in this repository as dependencies are linked to the local version (rather than whatever the state of those packages is on npm).

Each package is written in TypeScript and compiled to ES5 using rollup to the dist directory.

This should generally only happen at publishing time, but you may want to run npm run build prematurely during local development.

For example, let's say you're working on a pull request that

  1. adds support for a type in rich-text-types, and
  2. adds behavior to handle that type in rich-text-html-renderer.

If changes in the latter are dependent upon changes in the former, you'll need to run npm run build to update the referenced vendored files in rich-text-html-renderer.

All necessary dependencies are installed under node_modules and any necessary tools can be accessed via npm scripts. There is no need to install anything globally.

Creating commits

We follow Angular JS Commit Message Conventions to generate a changelog, enforced by commitizen. You'll need to use npm run commit to create conventional commits.

Code style

This project uses JavaScript Standard Style and Prettier conventions. Install a relevant editor plugin if you'd like. When in doubt, follow a style similar to the existing code :)

We use a common rollup config to compile packages from TypeScript to ES5. We also use common TypeScript and tslint configs. You'll notice the rollup.config.js and tsconfig.json in each package largely reference those files on a root level - this keeps code conventions consistent across the repository as a whole.

Running tests

We use Jest for unit tests. See Useful npm scripts above for some relevant npm commands.

Benchmarks

Some packages may contain benchmark scripts to prevent against performance regressions. We use Benchmark for these. Benchmarked files should be written in TypeScript with the same code style and formatting conventions as the rest of the codebase - we use ts-node (anchored to the Node version in ./node-version) to evaluate these.

Benchmarks are stored in the bin/benchmark folder of each relevant package. To run all benchmarks for a particular package, e.g. rich-text-links, you can run the npm benchmark script scoped to that package:

npm run benchmark @contentful/rich-text-links

or

npm run benchmark rich-text-links

Before submitting a pull request for a package with benchmarked code paths, please make sure that your changes do not negatively impact performance. (Of course, PRs improving performance are always welcome! 😄)

Publishing

We use Lerna to:

  • keep dependencies in sync
    • lerna bootstrap --hoist (which is run as a post-install step)
  • publish
    • NPM_CONFIG_OTP={2fa_otp_goes_here} npm run publish
    • As a community developer, you most likely won't have to worry about this step :)