Skip to content

Latest commit

 

History

History
158 lines (105 loc) · 5.9 KB

CONTRIBUTING.md

File metadata and controls

158 lines (105 loc) · 5.9 KB

Contributing

Contributions are always welcome, no matter how large or small!

Prerequisites

  • Node.js >= v14.15
  • Rust >= 1.61
  • Git >= 2.28 (for test-coverage)

Setup

On your first checkout of the repository, you'll need to install dependencies and build the project.

Rust

moon is built on Rust and requires rustup and cargo to exist in your environment. You can install Rust from the official website.

We also require the following 3rd-party Cargo commands, which can be installed with the following.

cargo install --force cargo-make # Required
cargo install --force cargo-nextest # Required for testing
cargo install --force cargo-insta # For testing snapshots

Once setup, we suggest building the Rust binary, as it's required for everything else.

cargo make build

Node.js

Contributing to our @moonrepo npm packages requires Node.js and Yarn. We suggest installing Node.js with nvm, and Yarn can later be installed with npm install -g yarn.

Once setup, install dependencies build initial packages.

yarn install

How to

Open development

All development on moon happens directly on GitHub. Both core team members and external contributors send pull requests which go through the same review process.

Branch organization

Submit all pull requests directly to the master branch. We only use separate branches for upcoming releases / breaking changes, otherwise, everything points to master.

Code that lands in master must be compatible with the latest stable release. It may contain additional features, but no breaking changes. We should be able to release a new minor version from the tip of master at any time.

Semantic versions

We utilize Yarn's release workflow for declaring version bumps and releasing packages. To enforce this standard, we have CI checks that will fail if a package has been modified, but a version bump has not been declared.

Reporting a bug

Please report bugs using the official issue template, only after you have previously searched for the issue and found no results. Be sure to be as descriptive as possible and to include all applicable labels.

The best way to get your bug fixed is to provide a reduced test case. Please provide a public repository with a runnable example, or a usable code snippet.

Requesting new functionality

Before requesting new functionality, view open issues as your request may already exist. If it does not exist, submit an issue using the official template. Be sure to be as descriptive as possible and to include all applicable labels.

Submitting a pull request

We accept pull requests for all bugs, fixes, improvements, and new features. Before submitting a pull request, be sure your build passes locally using the development workflow below.

Development workflow

The following commands are available and should be used in your standard development workflow.

Rust

To streamline development, we utilize cargo-make for common tasks.

  • cargo make build - Builds all crates into a single moon binary.
  • cargo make format - Formats code.
  • cargo make lint - Runs the linter.
  • cargo make test - Runs unit and integration tests.
  • cargo make test-coverage - Run tests and also generate code coverage reports.

Code coverage

We support source based code coverage with llvm-cov via unit and integration testing. To begin, install the necessary tooling:

rustup component add llvm-tools-preview
cargo install cargo-llvm-cov

Once installed, run cargo make test-coverage, which is a lengthy and time consuming process. This will build the binary in debug mode with instrumentation enabled, run all unit and integration tests, and generate a ton of *.profraw files in the repository (do not commit these!).

From here you can generate an HTML coverage report to ./coverage with cargo make generate-html. Open the index.html file to browse line-by-line coverage.

Once done, run cargo make clean-profraw to cleanup and remove all the *.profraw files.

Node.js

This repo is powered by moon itself, which means that each npm package is a distinct moon project. The list of projects can be found in .moon/workspace.yml.

  • yarn moon run <project>:build - Builds the package for distribution.
  • yarn moon run <project>:format - Formats code.
  • yarn moon run <project>:lint - Runs the linter.
  • yarn moon run <project>:test - Runs unit tests.
  • yarn moon run <project>:typecheck - Runs the type-checker.

Running all of these commands individually for all packages is quite involved, so you can also drop the project name to run the task in all projects. For example: yarn moon run :lint

Type checking

Type checking is performed by TypeScript. We prefer to run this first, as valid typed code results in valid tests and lints.

Testing

Tests are written with Jest. For every function or class, we expect an associated *.test.ts test file in the package's tests folder. We also write unit tests, not integration tests.

Linting

Linting is performed by ESLint. Most rules are errors, but those that are warnings should not be fixed, as they are informational. They primarily denote browser differences and things that should be polyfilled.

Formatting

Code formatting is performed by Prettier. We prefer to run Prettier within our code editors using format-on-save functionality.