Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (70 loc) · 3.29 KB

CONTRIBUTING.md

File metadata and controls

105 lines (70 loc) · 3.29 KB

Contributing

Thanks for contributing!

Development

We manage dependencies using npm. Note that for the time being, our development tools assume a Unix-like environment, which means Mac, Linux, or something like the Windows Subsystem for Linux.

Get set up with:

$ npm install
$ npm run test:install

to install the root project and our test fixtures.

Checks

Run these often -- unit tests and lint:

$ npm run lint
$ npm run test

# ... or all together ...
$ npm run check

Before submitting a PR...

Before you go ahead and submit a PR, make sure that you have done the following:

# Update the documentation TOCs (and commit changes).
$ npm run build

# Run lint and unit tests
$ npm run check

# After this, you can run the CLI tests which use real fixtures in E2E scenarios
# They're relatively slow (several seconds a test).
$ npm run test:cli

Using changesets

Our official release path is to use automation to perform the actual publishing of our packages. The steps are to:

  1. A human developer adds a changeset. Ideally this is as a part of a PR that will have a version impact on a package.
  2. On merge of a PR our automation system opens a "Version Packages" PR.
  3. On merging the "Version Packages" PR, the automation system publishes the packages.

Here are more details:

Add a changeset

When you would like to add a changeset (which creates a file indicating the type of change), in your branch/PR issue this command:

$ npm exec changeset

to produce an interactive menu. Navigate the packages with arrow keys and hit <space> to select 1+ packages. Hit <return> when done. Select semver versions for packages and add appropriate messages. From there, you'll be prompted to enter a summary of the change. Some tips for this summary:

  1. Aim for a single line, 1+ sentences as appropriate.
  2. Include issue links in GH format (e.g. #123).
  3. You don't need to reference the current pull request or whatnot, as that will be added later automatically.

After this, you'll see a new uncommitted file in .changesets like:

$ git status
# ....
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.changeset/flimsy-pandas-marry.md

Review the file, make any necessary adjustments, and commit it to source. When we eventually do a package release, the changeset notes and version will be incorporated!

Creating versions

On a merge of a feature PR, the changesets GitHub action will open a new PR titled "Version Packages". This PR is automatically kept up to date with additional PRs with changesets. So, if you're not ready to publish yet, just keep merging feature PRs and then merge the version packages PR later.

Publishing packages

On the merge of a version packages PR, the changesets GitHub action will publish the packages to npm.

Manually Releasing a new version to NPM

Only for project administrators
  1. Update CHANGELOG.md, following format for previous versions
  2. Commit as "Changes for version VERSION"
  3. Run npm version patch (or minor|major|VERSION) to run tests and lint, build published directories, then update package.json + add a git tag.
  4. Run npm publish and publish to NPM if all is well.
  5. Run git push && git push --tags