Skip to content

Latest commit

 

History

History
264 lines (178 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

264 lines (178 loc) · 10.7 KB
Raw

InstantSearch.js

Hello and welcome to the contributing guide for InstantSearch. 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 is developed in 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 ≥ 14 (current stable version) – nvm is recommended
  • Yarn

Launch the dev environment

We use Storybook to create stories for widgets.

yarn
cd packages/instantsearch.js
yarn storybook

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

Folders of the project

Here are the main files and folders of the project.

▸ examples/                            << Examples, grouped per flavor
▸ packages/                            << Packages of the project
  ▸ react-instantsearch/               << Bundled React InstantSearch library
  ▸ react-instantsearch-core/          << Runtime-independent React InstantSearch version
  ▸ react-instantsearch-dom/           << DOM-specific React InstantSearch version
  ▸ react-instantsearch-native/        << React Native-specific InstantSearch version
  ▸ react-instantsearch-dom-maps/      << DOM-specific React InstantSearch version with Google Maps

  ▸ react-instantsearch-hooks/        << React InstantSearch Hooks library
  ▸ react-instantsearch-hooks-web/    << DOM-specific React InstantSearch Hooks version
  ▸ react-instantsearch-hooks-server/ << Server-specific React InstantSearch Hooks version

  ▸ instantsearch.js/                  << The InstantSearch.js library
▸ tests/                               << The test utilites
  ▸ mocks/                             << Fake versions of the API, for testing
  ▸ utils/                             << Global utilities for the tests
▸ website/                             << The generated website
▸ scripts/                             << The scripts for maintaining the project
  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

Importing existing projects

This monorepo has as goal to be used for all InstantSearch flavors and tools. To do so, we need to import existing projects into this repository. The process is as follows:

  1. clone your project into a new clean folder (/tmp/myproject)
  2. install git-filter-repo
  3. run git filter-repo --to-subdirectory-filter packages/myproject
  4. add your temporary clone as a remote in the instantsearch repository: git remote add myproject /tmp/myproject
  5. fetch the remote: git fetch myproject
  6. check out to a new branch: git checkout -b feat/import-myproject
  7. merge the remote into the monorepo: git merge --allow-unrelated-histories myproject/mybranch
  8. replace commit messages which refer to issues/PRs with #xxx by also referencing the original repo: git filter-branch --msg-filter 'sed -E "s/(#[[:digit:]]+)/algolia\/myproject\1/"' master..feat/import-myproject
  9. make any changes necessary to make the project work in the monorepo and commit those
  10. make a pull request and merge using rebase or merge (if you merge using squash the history will be lost)

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

End-to-end tests

End-to-end tests are defined in tests/e2e.

To run them locally:

yarn test:e2e:local

To run them on Sauce Labs:

yarn test:e2e:saucelabs

Note Make sure to set up Sauce Labs credentials with the SAUCE_USERNAME and SAUCE_ACCESS_KEY environment variables.

For more info, including how to write end-to-end tests, check the tests/e2e CONTRIBUTING and README files.

Type checks

Type checks ensure code is correctly typed both for code quality and TypeScript compatibility.

To ensure typing is correct in the latest version of InstantSearch.js, you can run the following command:

yarn type-check

Since we still support algoliasearch@3, you should also type check against v3.x.

./scripts/legacy/downgrade-algoliasearch-dependency.js
yarn type-check:v3

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

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

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.