Skip to content

Latest commit

 

History

History
212 lines (142 loc) · 11.1 KB

CONTRIBUTING.md

File metadata and controls

212 lines (142 loc) · 11.1 KB
Raw

Contributing

First of all, thank you for contributing to Meilisearch! The goal of this document is to provide everything you need to know in order to contribute to Meilisearch and its different integrations.

Assumptions

  1. You're familiar with GitHub and the Pull Request (PR) workflow.
  2. You've read the Meilisearch documentation and the README.
  3. You know about the Meilisearch community. Please use this for help.

How to Contribute

  1. Make sure that the contribution you want to make is explained or detailed in a GitHub issue! Find an existing issue or open a new one.
  2. Once done, fork the instant-meilisearch repository in your own GitHub account. Ask a maintainer if you want your issue to be checked before making a PR.
  3. Create a new Git branch.
  4. Review the Development Workflow section that describes the steps to maintain the repository.
  5. Make the changes on your branch.
  6. Submit the branch as a PR pointing to the main branch of the main instant-meilisearch repository. A maintainer should comment and/or review your Pull Request within a few days. Although depending on the circumstances, it may take longer.
    We do not enforce a naming convention for the PRs, but please use something descriptive of your changes, having in mind that the title of your PR will be automatically added to the next release changelog.

Development Workflow

Setup

yarn --dev

Tests and Linter

Each PR should pass the tests and the linter to be accepted.

# Tests with Jest
docker pull getmeili/meilisearch:latest # Fetch the latest version of Meilisearch image from Docker Hub
docker run -p 7700:7700 getmeili/meilisearch:latest meilisearch --master-key=masterKey --no-analytics
# Integration tests
yarn test
# End-to-end tests
yarn test:e2e
# Linter
yarn lint
# Linter with fixing
yarn lint:fix
# Build the project
yarn build

If you want to test a specific package, from the root directory run any of the above command with the filter flag.

Example:

turbo run test --filter=@meilisearch/instant-meilisearch

Versioning with Changesets

⚠️ This step is crucial to merge a PR containing impacting changes for the package(s)! ⚠️

💡 Example of PR that does NOT require a changeset: updating the README.md or changes in tests files.

We use changesets to do versioning.

For each PR that changes something in the package(s), you need to add a changeset by running yarn changeset.

This command will run questions:

  • select the packages concerned by the PR changes
  • indicate how these changes impact the version (press enter to skip the question if you don't want to upgrade the major or the minor)
  • Write a brief summary of the changes

Modification will be applied to the .changesets directory. These changes should added to your PR.

Before the release, the new files in .changesets will be automatically removed. See our release process.

Playgrounds

@meilisearch/instant-meilisearch playgrounds

To test directly your changes in @meilisearch/instant-meilisearch, you can run the following playgrounds:

Vue 3

yarn playground:vue

React:

yarn playground:react

Vanilla JS:

yarn playground:javascript

HTML:

yarn playground:html

An additional playground is provided to test out the GeoSearch.

yarn playground:geosearch

Note: If the Google Maps stopped working, please create a new Google Api Key and add it in the .env file at the root of the playground: /playgrounds/geo-javascript

@meilisearch/instant-meilisearch playgrounds

To test directly your changes made in @meilisearch/autocomplete-client, you can run the following playground:

yarn playground:autocomplete

Git Guidelines

Git Branches

All changes must be made in a branch and submitted as PR. We do not enforce any branch naming style, but please use something descriptive of your changes.

Git Commits

As minimal requirements, your commit message should:

  • be capitalized
  • not finish by a dot or any other punctuation character (!,?)
  • start with a verb so that we can read your commit message this way: "This commit will ...", where "..." is the commit message. e.g.: "Fix the home page button" or "Add more tests for create_index method"

We don't follow any other convention, but if you want to use one, we recommend this one.

GitHub Pull Requests

Some notes on GitHub PRs:

  • Convert your PR as a draft if your changes are a work in progress: no one will review it until you pass your PR as ready for review.
    The draft PR can be very useful if you want to show that you are working on something and make your work visible.
  • The branch related to the PR must be up-to-date with main before merging. Fortunately, this project integrates a bot to automatically enforce this requirement without the PR author having to do it manually.
  • All PRs must be reviewed and approved by at least one maintainer.
  • The PR title should be accurate and descriptive of the changes. The title of the PR will be indeed automatically added to the next release changelogs.

Release Process (for the internal team only)

Meilisearch tools follow the Semantic Versioning Convention.

Automation to Rebase and Merge the PRs

This project integrates a bot that helps us manage pull requests merging.
Read more about this.

Release on GitHub and npm

This repository uses the changesets library to handle the version updates and the publishing on GitHub and npm.

⚠️ Each PR merged on main involving a change in the package(s) should contain modifications in the .changeset folder. See changeset section.

Each merge on main triggers the release CI generating a PR titled Version Packages. This PR updates the versions and contains changelogs of the impacted packages based on the yarn changesets commands you ran on each PR.

To release on GitHub and npm you must merge this Version packages PR. This will trigger the publishing action and create the GitHub and npm releases for all affected packages.

See more in depth explaination on versioning, publishing and the changesets github-action.

If you merged a beta branch, that was released, into main, you were probably in the changesets pre-release mode (see section on releasing a beta). If the pre.json file is present in the .changesets folder, you need to exit that mode. This is possible by running yarn changeset pre exit. Once done, create a PR with the changes and merge it to main.

Codesandbox update

Once the version is available on npm, please update the instant-meilisearch version used in the different Code-Sandboxes we provide:

If you don't have the access to do it, please request it internally.

Release a beta Version

This package is able to create multiple types of betas:

  • A standard package beta, working on the latest version of Meilisearch.
  • A beta implementing the changes of a rc version of Meilisearch.
  • A beta implementing a specific feature prototype of Meilisearch.

Here are the steps to release a beta version of this package depending on its type:

  1. Create a new branch containing the changes with the correct name format following these rules:

    • package beta: create a branch beta/xx-xx with the context of your beta. Example: beta/refactor.
    • Meilisearch pre-release beta: create a branch originating from bump-meilisearch-v*.*.* named pre-release-beta/v*.*.*.
      Example: pre-release-beta/v0.30.0
    • Meilisearch prototype beta: create a branch prototype-beta/xx-xx. Where xxx has the same name as the docker image containing the prototype. Example: If the docker image is named: prototype-multi-search-0, the branch should be named: prototype-beta/prototype-multi-search

  2. Enable the pre-release mode by running yarn changeset pre enter [X]. X is the part after the / of your beta branch. Example for beta/refactor, X would be refactor. This will create a pre.json file in .changesets that must be pushed on your beta branch.

  3. Commit and push your related PRs to the newly created branch (step 1).

  4. When a PR is merged onto your beta branch, the release CI opens a PR named Version Packages (X) (see step 2 for X). This PR contains all the changesets and the version update based on the type of changes in the changesets.

  5. To publish the release on GitHub and npm, you need to merge the Version Packages (X) PR. This will trigger the publishing.

Thank you again for reading this through. We can not wait to begin to work with you if you make your way through this contributing guide ❤️