Skip to content
This repository has been archived by the owner on May 21, 2020. It is now read-only.

Latest commit

 

History

History
230 lines (152 loc) · 8.81 KB

CONTRIBUTING.md

File metadata and controls

230 lines (152 loc) · 8.81 KB
Raw

InstantSearch.js

Hello and welcome to the contributing guide for InstantSearch.js. Thanks for considering participating in our project 🙇

If this guide does not contain what you are looking for and thus prevents you from contributing, don't hesitate to leave a message on the community forum or to open an issue.

Reporting an issue

Opening an issue is very effective way to contribute because many users might also be impacted. We'll make sure to fix it quickly if it's technically feasible and doesn't have important side effects for other users.

Before reporting an issue, first check that there is not an already open issue for the same topic using the issues page. Don't hesitate to thumb up an issue that corresponds to the problem you have.

Another element that will help us go faster at solving the issue is to provide a reproducible test case. We often recommend to use this CodeSandbox template.

The code contribution process

InstantSearch.js was first developed in JavaScript and is now being migrated to TypeScript.

For any code contribution, you need to:

  • Fork and clone the project
  • Create a new branch for what you want to solve (fix/issue-number, feat/name-of-the-feature)
  • Make your changes
  • Open a pull request

Depending on what you're working on, you might consider different base branches.

Then:

  • Peer review of the pull request (by at least one of the core contributors)
  • Automatic checks (tests, commits, linters)
  • When everything is green, your contribution is merged 🚀

After you create a pull request, a bot will comment with a link to a development version of the website.

You will find a playground for the widgets, for example: https://deploy-preview-3376--instantsearchjs.netlify.com/stories/

Commit conventions

This project follows the conventional changelog approach. This means that all commit messages should be formatted using the following scheme:

type(scope): description

In most cases, we use the following types:

  • fix: for any resolution of an issue (identified or not)
  • feat: for any new feature
  • refactor: for any code change that neither adds a feature nor fixes an issue
  • docs: for any documentation change or addition
  • chore: for anything that is not related to the library itself (doc, tooling)

Even though the scope is optional, we try to fill it in as it helps us better understand the impact of a change. We either use the name of the widget/connector/component impacted or we use impact topic (e.g. docs, tooling, deps, ci).

Finally, if your work is based on an issue on GitHub, please add in the body of the commit message "fix #1234" if it solves the issue #1234 (read "Closing issues using keywords").

Some examples of valid commit messages (used as first lines):

  • fix(searchbox): increase magnifying glass size
  • chore(deps): update dependency rollup-plugin-babel to v3.0.7
  • fix(connectRefinementList): set default value for limit
  • chore: reword contributions guides

Branch organization

The project is based on the classic GitHub flow:

  • master for the current version being worked on – Pull requests for bugs and feature related to the current major version should be created against this branch
  • vX for each major version (X being a number) – Pull requests for critical bug fixes should be created against this branch

Most of the time, your pull requests should target the master branch.

Note that no new features will be developed or backported for the vX branches.

Requirements

To run this project, you will need:

  • Node.js ≥ 8 (current stable version) – nvm is recommended
  • Yarn

Launch the dev environment

We use Storybook to create stories for widgets.

yarn
yarn dev

Go to http://localhost:6006 for the widget playground.

Folders of the project

Here are the main files and folders of the project.

▸ .storybook/         << the storybook configuration source
▸ scripts/            << the scripts for maintaining the project
▸ src/                << the source of the library
▸ stories/            << the widget stories
▸ website/            << the website source
  CHANGELOG.md        << the autogenerated changelog (based on commits)
  CONTRIBUTING.md     << this file
  package.json        << the definition of the project
  README.md           << the introduction of the project

The source folder

▸ src/
  ▸ components/       << The Preact components for the UI of our widgets
  ▸ connectors/       << The source of all the connectors driving the widgets' logic
  ▸ helpers/          << The source of the method helpers
  ▸ lib/              << The core of the library (InstantSearch, routers, etc.)
  ▸ types/            << The TypeScript declarations
  ▸ widgets/          << The source of the widgets

Tests

Unit tests

Our unit tests are written with Jest:

To run all the tests once:

yarn test

To run the test continuously based on what you changed (useful when developing or debugging):

yarn test --watch

Linting

Linters are static checkers for code. They help us maintain a consistent code base. They are used for JavaScript and TypeScript files.

If your editor support them, then you will see the errors directly there. You can also run them using your command line:

yarn lint

JavaScript and TypeScript files are validated using a combination of Prettier (strict syntax form) and ESLint rules (for common mistakes and patterns).

Release

Main version

To release a stable version, go on master (git checkout master) and use:

yarn run release:prepare

It will create a pull request for the next release. When it's reviewed, approved and merged, then CircleCI will automatically publish it to npm.

Maintenance versions

For the maintenance versions, go to a previous version branch (e.g., git checkout v3) and use:

npm run release:maintenance

Make sure to use npm run instead of yarn run to avoid issues.

next version

next version release is available on the next branch. It is used to release the next major version in beta.

git checkout next
yarn run release:prepare

The script will ask you a question about the next version. If it's wrong, you can say "No" and specify the version (e.g. "7.0.0-beta.0"). Then, it will open a pull request for that release. When the pull request is merged, CircleCI will publish it to npm with a --tag beta argument.

Experimental TypeScript version

An experimental version containing the TypeScript declaration files is available on the npm tag experimental-typescript.

Since some of these declaration files are generated from the JSDoc comments, they can contain some typing errors. This version will stay experimental until we are confident enough in the generated declarations to put them in a stable release.

To generate the experimental TypeScript version for a particular (stable) release, run:

./scripts/release/build-experimental-typescript.js

To publish it manually, run:

npm publish --tag experimental-typescript
# or
yarn publish --no-git-tag-version --non-interactive --tag experimental-typescript

Note that this build will be automatically published along with the current stable version by Ship.js.