Skip to content

Latest commit

 

History

History
234 lines (173 loc) · 12.1 KB

CONTRIBUTING.md

File metadata and controls

234 lines (173 loc) · 12.1 KB
Raw

Contributing

First of all, thank you for contributing to Meilisearch! This document aims to provide everything you need to know to contribute to this Meilisearch integration.

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 cloud-providers 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 cloud-providers 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, keeping in mind that the title of your PR will be automatically added to the following release changelog.

You can check out the more extended, complete guideline documentation here.

Development Workflow

Setup

  1. Install the Packer CLI
  2. Set up all your needed credentials
  • AWS: Obtain your AWS access keys and set it in your environment: 
      export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY"
  export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_KEY"
  • DigitalOcean: Before running any script, make sure to obtain a DigitalOcean API Token and set it in your environment: 
    export DIGITALOCEAN_ACCESS_TOKEN="XxXxxxxXXxxXXxxXXxxxXXXxXxXxXX"
  • GCP: Obtain your GCP credentials and set it in your environment: 
    export GOOGLE_APPLICATION_CREDENTIALS="path_to_your_creadential_file.json"
  1. Download and install Packer plugins 
    packer init .

Tests and Linter

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

Use this command to format HCL2 configuration file:

packer fmt .

Use this command to validate the syntax and configuration of the template:

packer validate .

Build the images

⚠ Please be aware that this command will create all new Meilisearch images on all platforms.

This command will execute the template and build all images in parallel:

packer build meilisearch.pkr.hcl

You can build one or more images by specifying their name, take the first parameter given to source block and add it the following wildcard regex: .*. Example:

packer build -only 'amazon-ebs.*' .

Add a new provider

There are multiple providers available for Packer, you can check the External Plugins Documentation

To add a provider correctly to the list of existing providers, proceed as follows:

  1. Add your code to the primary meilisearch.pkr.hcl file as expected.
  • Incorporate specific variables into the variables block at the beginning of the file if necessary.
  • Introduce the plugin of your new provider into the packer block.: 
    packer {
required_plugins {
  ...
  mynewprovider = {
      ...
    }
  }
}
  • Lastly, you will need to create a new source block for your provider. To accomplish this, please consult the specific documentation for each plugin as your guide. 
    source "mynewprovider" "debian" {
  ...
}
  1. Add the provider name to the README.
  2. Add a manual trigger for your new provider to the CI by adding it to the list of suppliers in the option block of manual_publish.yml.

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)

Meilisearch tools follow the Semantic Versioning Convention.

The release tags of this package follow exactly the Meilisearch versions.
For example, the v1.1.1 tag in this repository corresponds to the image running Meilisearch v1.1.1.

Please follow the steps in the next sections carefully before any release.

Automated Publishing

Building and deploying all new Meilisearch images on all platforms is done automatically by a github action when a new tag is pushed to main.

Release, Build and Publish

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

  1. In the file meilisearch.pkr.hcl, update the value of the default variable in the block meilisearch_version with the new version of Meilisearch you want to release, in the format: vX.X.X.
  2. Commit your changes to a new branch.
  3. Open a PR from the branch where changes were done and merge it.
  4. 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

This will start building and publishing all images on all platforms.

💡 You can publish each image manually if a publication did not go well: you can manually launch each building image separately in the GitHub interface.

  • Click on the Action tab.
  • Choose the "Publish Manually" action on the left sidebar.
  • On the right side of the screen, select the Use workflow from panel.
  • On Use workflow from keep Branch: main.
  • On Choose the provider you want to publish select the provider you want to re-deploy.

Publish the AWS image

Nothing to do! The image is immediatly available on AWS. You can see the new created image here (Images -> AMI)

Publish the DigitalOcean image

In the DigitalOcean Vendor Portal, click on the title of the MeiliSearch image (type: Droplet 1-Click). A form will open for a new image submission. Update the information regarding the latest version in the document:

  • Update the App version (with the version number, without the starting v, so vX.X.X becomes X.X.X).
  • In the System image field, click Select system image and select the image you tested from the list (Meilisearch-v.X.X.X-Debian-X).
  • In the Software Included field, update the Meilisearch version.
  • Check the Application summary, Application Description, and Getting started instructions fields for any conflicting information that should be updated about Meilisearch usage or installation.
  • In the Reason for update field, write "Bump Meilisearch to vX.X.X".
  • Verify the form, and hit on Submit.

⚠️ When the image is submitted to the Marketplace, Meilisearch will immediately lose its ownership. The submitted image won't appear in the organization dashboard anymore, and no further modification can be done.

This will start the DigitalOcean review process. This can take a few days, and the result will be notified via email to the DigitalOcean admin account. If the image is accepted, it will be automatically published on the Marketplace. If it is rejected, an email explaining the problems will be sent to administrators.

Create the Virtual disk (VMDK) for GCP

In the GCP console

  • Ensure you selected the MeiliSearchImage project in the GCP console
  • Navigate to "Compute Engine" -> "Images"
  • Click on the image you just created meilisearch-X-X-X-debian-X
  • Click on EXPORT
  • On: "Export format" choose VMDK
  • On: "Path*" click on BROWSE and select meilisearch-image
  • Validate it by clicking on the SELECT button at the bottom
  • Finally click on the EXPORT button at the buttom

The new image should appear in the list. It might take a few minutes.

Cleaning old images (Optional)

You may want to clean up the old images.

Digital Ocean

For DigitalOcean, each new image submitted deletes the old one.

However if you have made a copy so that it is available from the dashboard:

  • Go to the DO console
  • Go to Images -> Manage (left side bar)
  • On the list of image, for the chosen image, click on More -> Delete

GCP

  • Go to Cloud-storage: GCP console > Cloud Storage
  • Click on `meilisearch-image``. You will have access to a list of all vdmk images
  • Select the images you wish to delete
  • Click on DELETE (at top of the list)

AWS

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