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

Latest commit

 

History

History
168 lines (108 loc) · 9.49 KB

CONTRIBUTING.md

File metadata and controls

168 lines (108 loc) · 9.49 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 meilisearch-gcp 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. Make the changes on your branch.
  5. Submit the branch as a PR pointing to the main branch of the main meilisearch-gcp 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 

pip3 install -r requirements.txt

Tests and Linter

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

# Linter
pylint tools

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. If it's not, you have to rebase your branch. Check out this quick tutorial to successfully apply the rebase from a forked repository.
  • All PRs must be reviewed and approved by at least one maintainer.
  • The PR title should be accurate and descriptive of the changes.

Release Process (for the internal team only)

⚠️ The cloud-scripts repository should be upgraded to the new version before this repository can be updated and released.

The release tags of this package follow exactly the Meilisearch versions.
It means that, for example, the v0.17.0 tag in this repository corresponds to the GCP image running Meilisearch v0.17.0.

This repository currently does not provide any automated way to test the GCP Meilisearch image.
Please, follow carefully the steps in the next sections before any release.

Set your environment

After cloning this repository, install python dependencies with the following command:

pip3 install -r requirements.txt

Before running any script, make sure to set your GCP credentials locally. Make sure that youhave access to the project meilisearchimage, or ask a maintainer for a Service Account access.

Test before Releasing

  1. Add your SSH key to the Compute Engine platform, on the metadata section. Set the name of the user defined on your SSH key as a value for the SSH_USER variable in the tools/config.py script. (I.E. If your SSH key finishes by myname@mylaptop use myname as the value of SSH_USER)

  2. In tools/config.py, update the MEILI_CLOUD_SCRIPTS_VERSION_TAG variable value with the new Meilisearch version you want to release, in the format: vX.X.X. If you want to test with a Meilisearch RC, replace it by the right RC version tag (vX.X.XrcX).

  3. Run the tools/build_image.py script to build the GCP custom image without analytics:

python3 tools/build_image.py --no-analytics

This command will create an GCP Compute Instance on Meilisearch's account and configure it in order to prepare the Meilisearch custom image. It will then create an Image, which should be ready to be published in the following steps. The instance will automatically be terminated after the custom image creation.
The image name will be Meilisearch-vX-X-X-ubuntu-X--lts-build--XX-XX-XXXX.

  1. Test the image: create a new GCP Compute instance based on the new image Meilisearch-vX-X-X-ubuntu-X--lts-build--XX-XX-XXXX, and make sure everything is running smoothly. Remember to check the following checkboxes: Allow HTTP traffic and Allow HTTPS traffic. Connect via SSH to the droplet and test the configuration script that is run automatically on login. Use the same username defined in the step 1 and in the SSH key you have set on GCP.
    🗑 Don't forget to destroy the Droplet after the test.

  2. When you are ready to create the final image to release juste remove the --no-analytics option

python3 tools/build_image.py

Publish the GCP image and Release

⚠️ The GCP image should never be published with a RC version of Meilisearch.

Once the tests in the previous section have been done:

  1. Set the image name that you TESTED and you want to publish as the value of the PUBLISH_IMAGE_NAME in tools/config.py. Use the exact name of the IMAGE that you built in the previous step: Meilisearch-vX-X-X-ubuntu-X--lts-build--XX-XX-XXXX.

  2. Run the tools/publish_image.py script to export and publish the GCP image:

python3 tools/publish_image.py

  1. Commit your changes on a new branch.

  2. Open a PR from the branch where changes where done and merge it.

  3. Create a git tag on the last main commit:

git checkout main
git pull origin main
git tag vX.X.X
git push origin vX.X.X

⚠️ If changes where made to the repository between your testing branch was created and the moment it was merged, you should consider building the image and testing it again. Some important changes may have been introduced, unexpectedly changing the behavior of the image that will be published to the Marketplace.

Clean old GCP images

Make sure that the last 2 versions of the Meilisearch image are available and public. Our goal is to always offer the latest Meilisearch version to GCP users, but we are keeping the previous version in case there is a bug or a problem in the latest one. Any other older version of the image must be deleted.

To proceed to delete older images that should no longer be available, use the GCP user interface, since this task hasn't yet been automated.

Update the GCP image between two Meilisearch Releases

It can happen that you need to release a new GCP image but you cannot wait for the new Meilisearch release.
For example, the v0.17.0 is already pushed but you find out you need to fix the installation script: you can't wait for the v0.18.0 release and need to re-publish the v0.17.0 GCP image.

In this case:

  • Apply your changes and reproduce the testing process (see Test before Releasing).
  • Delete the current tag remotely and locally:
git push --delete origin vX.X.X
git tag -d vX.X.X

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 ❤️