Skip to content

Latest commit

 

History

History
364 lines (270 loc) · 13.9 KB

CONTRIBUTING.md

File metadata and controls

364 lines (270 loc) · 13.9 KB

InstantSearch.js

Hello and welcome to the contributing guide 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 open an issue.

Contributing with an new issue ⚠️

Opening an issue is very useful for us so don't hesitate, we'll make sure to fix it as soon as possible if it's technically feasible and doesn't have important side effects for the other users.

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

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 🤘

On your side:

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

Depending on what you're working, 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.

On it you can find:

  1. The generated documentation: https://deploy-url-netlify/
  2. A playground for the widgets: https://deploy-url-netlify/v2/dev-novel

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 anything that contains the resolution of an issue (identified or not)
  • feat: for anything that contains a new feature
  • 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 the kind of part of the project it will impact, for example: docs, tooling, 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.

Some examples of valid commit messages (first line):

  • fix(searchbox): make magnifying glass bigger
  • chore(deps): update dependency style-loader to v0.19.0
  • fix(connectRefinementList): set default value for limit
  • chore: reword contributions guides

Branches organization 🌳

The project is based on the classic GitHub flow because we are building a library and each version must be crafted with care. We also maintain a branch specific for the older version of the library (currently v1). Finally, when building feature (that will go in the next minor version) we have specific branch.

To sum up, we have:

  • develop for the version -- Pull requests for bugs should be created against this branch
  • feat/2.* for the next minor version -- Pull requests for features should be created against this branch
  • master for the current stable version -- we usually don't make pull requests for this branch
  • maintenance for the previous major version (currently v1) -- Pull requests for critical bug fixes on the old version

You should do the dev and create pull requests according to the target version.

NB: No new features will be done on the maintenance version.

Requirements

To run this project, you will need:

Launch the dev environment 👩‍💻

During the development, we use two main tools. The dev app / playground in which we create stories for the different widgets and the documentation website which has create API documentation based on the JSDoc comments.

yarn
yarn dev

Go to http://localhost:8080 for the example playground.

Go to http://localhost:3000 for the documentation website.

Updating the examples

To update the documentation examples, you must re-build the InstantSearch.js library each time you change it via:

yarn build

And also relaunch the dev environement afterwards.

Folders of the project 🗺

Here are the main files and folders of the project.

▸ dev/                << the dev app source
▸ docgen/             << the documentation source
▸ functional-tests/   << the functional tests
▸ scripts/            << the scripts for maintaining the project
▸ src/                << the source of the library
  CHANGELOG.md        << the autogenerated changelog (based on commits)
  CONTRIBUTING.md     << this file
  index.es6.js        << the root js file for the ES6 module
  index.js            << the root js file for the bundle
  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 (UI)
  ▸ connectors/       << The source of all the connectors (UX without UI)
  ▸ css/              << The source of the themes (reset / algolia theme)
  ▸ decorators/       << Preact HoC that factorize some behaviour of the widgets
  ▸ lib/              << The core of the library, instantsearch, url
  ▸ widgets/          << The source of the widgets (UX + UI)

The documentation source

▾ docgen/
  ▸ assets/                         << static assets
  ▸ layouts/                        << pug files that define the structure of the pages
  ▸ plugins/                        << custom metalsmith plugins
  ▸ src/                            << Source for the editorial content
    build.js                        << build script (prod)
    builder.js                      << main js file of the doc builder
    config.js                       << variables definition for the build
    devServer.js                    << config for the dev server
    mdRenderer.js                   << customized md renderer
    middlewares.js                  << metalsmith plugins definitions
    package.json
    path.js                         << path config file
    postcss.config.js               << postcss config file
    start.js                        << build script (dev)
    syntaxHighlighting.js           << customized syntax highlighting
    webpack.config.babel.js         << common webpack config
    webpack.config.build.babel.js   << prod webpack config
    webpack.config.start.babel.js   << dev webpack config

The dev app

▾ dev/
  ▾ app/                      << the source of the dev app
    ▸ custom-widgets/         << the source of the custom widgets to validate the connector API
    ▸ templates/              << templates used for the common widgets
      index.js                << main script of the dev app
      init-builtin-widgets.js << initialization of the IS.js app with built-in widgets
      init-jquery-widgets.js  << initialization of the IS.js app with custom widget / jQuery
      init-vanilla-widgets.js << initialization of the IS.js app with other custom widgets
      wrap-with-hits.js       << utility source that adds a hits and searchbox for each story
    style.css
    template.html
    webpack.config.js

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 # unit tests watch mode, no lint

Functional tests

We have one functional test ensuring that when we instantiate a full app with a searchBox, we are able to use it and get different hits than initially.

Functional tests are built with webdriver.io, a wrapper around WebDriver API (Selenium). On travis they will run on different browsers using Sauce Labs.

Local setup

Locally it will use a docker image bundling Selenium and browsers.

docker pull elgalu/selenium
# this helps in loading the host website from the container,
# comes from https://docs.docker.com/docker-for-mac/networking/#known-limitations-use-cases-and-workarounds
docker run -d --name=grid -p 4444:24444 -p 6080:26080 -p 5900:25900 \
    -e TZ="US/Pacific" -e NOVNC=true -v /dev/shm:/dev/shm --privileged elgalu/selenium

Running locally

# We want to access the host machine from the container (to reach the test app web server).
# Needed once per session, this is not persistent:
sudo ifconfig lo0 alias 10.200.10.1/24
npm run test:functional
# npm run test:functional:dev will reload tests when file changes
# npm run test:functional:dev:debug will load the test website locally for you to open it
# if something goes wrong: docker restart grid && killall node

Locally you can inspect (view) the browser doing the test here: http://localhost:6080/.

Debugging

In order to check the status of the functional tests on all the platforms we use sauce labs. The first here is to get the credentials of your sauce labs account.

Running the functional tests on sauce labs:

SAUCE_USERNAME=[your login] SAUCE_ACCESS_KEY=[your api key] CI=true yarn run test:functional

You can then inspect the status of tests from your dashboard. Check the browsers for which tests are failing. If some are IE or Edge you can download a virtual machine image from the Microsoft website.

Update the config of the dev server (instantsearch.js/scripts/dev.sh) so that you can access the test page with your VM. Do not commit this change

- webpack-dev-server --config dev/webpack.dev.config.babel.js --hot --inline --no-info &
+ webpack-dev-server --config dev/webpack.dev.config.babel.js --hot --inline --no-info --public [your_ip] &

Then you should be able debug using the dev setup: yarn run dev and the virtual machine. You can also run the page used for function tests using yarn run test:functional:dev:debug-server

Linting ✨

Linters are static checkers for the code. They help us maintain a consistent code base. They are used for js and SCSS 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

The JS files are validated using a combination of prettier (strict syntax form) and eslint rules (for common mistakes and patterns). The scss linter uses sass-lint.

Release 🛳

Main version

For the main version, go on develop (git checkout develop) and use:

npm run release

Be sure to use $ npm run instead of $ yarn run to avoid issues

Maintenance version

For the maintenance version, go on maintenance (git checkout maintenance) and use:

npm run release-maintenance

Be sure to use $ npm run instead of $ yarn run to avoid issues

Beta version β

Beta version release is available on any branch except master, maintenance. The main use cases are for releasing a patch before the official release, or create custom builds with new features (or friday releases).

If you're on a feature branch (either for a fix or a new minor/major version), you can run:

npm run release

You can also release a beta version from develop, using the beta flag in the command line:

npm run release -- --beta

Be sure to use $ npm run instead of $ yarn run to avoid issues

Updating the docs 📚

The documentation website is created and pushed during the release of main version.