From c9cc504e7b957368a8ee6f42aa6f4bb84fb9af3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9mentine=20Urquizar?= Date: Mon, 27 Sep 2021 14:13:50 +0200 Subject: [PATCH] Update CONTRIBUTING.md --- CONTRIBUTING.md | 136 ++++++++++++++++++------------------------------ 1 file changed, 52 insertions(+), 84 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c8abd2e6..058b49d0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,112 +1,80 @@ # Contributing -First, thank you for contributing to MeiliSearch! The goal of this document is to -provide everything you need to start contributing to MeiliSearch. The -following TOC is sorted progressively, starting with the basics and -expanding into more specifics. +First, thank you for contributing to MeiliSearch! The goal of this document is to provide everything you need to start contributing to MeiliSearch. - - -1. [Assumptions](#assumptions) -1. [Your First Contribution](#your-first-contribution) -1. [Change Control](#change-control) - 1. [Git Branches](#git-branches) - 1. [Git Commits](#git-commits) - 1. [Style](#style) - 1. [Github Pull Requests](#github-pull-requests) - 1. [Reviews & Approvals](#reviews--approvals) - 1. [Merge Style](#merge-style) - 1. [CI](#ci) -1. [Development](#development) - 1. [Setup](#setup) - 1. [Testing](#testing) - 1. [Benchmarking](#benchmarking--profiling) -1. [Humans](#humans) - 1. [Documentation](#documentation) - 1. [Changelog](#changelog) - - +- [Assumptions](#assumptions) +- [How to Contribute](#how-to-contribute) +- [Development Workflow](#development-workflow) +- [Git Guidelines](#git-guidelines) ## Assumptions -1. **You're familiar with [Github](https://github.com) and the [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) - workflow.** -2. **You've read the MeiliSearch [docs](https://docs.meilisearch.com).** +1. **You're familiar with [Github](https://github.com) and [Pull Request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)(PR) workflow.** +2. **You've read the MeiliSearch [documentation](https://docs.meilisearch.com).** 3. **You know about the [MeiliSearch community](https://docs.meilisearch.com/learn/what_is_meilisearch/contact.html). Please use this for help.** -## Your First Contribution +## How to Contribute 1. Ensure your change has an issue! Find an [existing issue](https://github.com/meilisearch/meilisearch/issues/) or [open a new issue](https://github.com/meilisearch/meilisearch/issues/new). * This is where you can get a feel if the change will be accepted or not. -2. Once approved, [fork the MeiliSearch repository](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) in your own - Github account. +2. Once approved, [fork the MeiliSearch repository](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) in your own Github account. 3. [Create a new Git branch](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository) -4. Review the MeiliSearch [workflow](#workflow) and [development](#development). -5. Make your changes. -6. [Submit the branch as a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) to the main MeiliSearch - repo. A MeiliSearch team member should comment and/or review your pull request - with a few days. Although, depending on the circumstances, it may take - longer. +4. Review the [Development Workflow](#development-workflow) section that describes the steps to maintain the repository. +5. Make your changes on your branch. +6. [Submit the branch as a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) pointing to the `main` branch of the main 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.r. -## Change Control +## Development Workflow + +### Setup and run MeiliSearch + +```bash +cargo run +``` + +We recommend using the `--release` flag to test the full performance of MeiliSearch. + +### Test + +```bash +cargo test +``` + +If you get a "Too many open size" error you might want to increase the open file limit using this command: + +```bash +ulimit -Sn 3000 +``` + +## Git Guidelines ### Git Branches -_All_ changes must be made in a branch and submitted as [pull requests](#pull-requests). -MeiliSearch does not adopt any type of branch naming style, but please use something -descriptive of your changes. +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 -#### Style +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" -Please ensure your commits are small and focused; they should tell a story of -your change. This helps reviewers to follow your changes, especially for more -complex changes. - -Familiarise yourself with [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). +We don't follow any other convention, but if you want to use one, we recommend [this one](https://chris.beams.io/posts/git-commit/). ### Github Pull Requests -Once your changes are ready you must submit your branch as a pull request. +Some notes on GitHub PRs: -#### Reviews & Approvals +- All PRs must be reviewed and approved by at least one maintainer. +- The PR title should be accurate and descriptive of the changes. +- [Convert your PR as a draft](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request) 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 [Bors](https://github.com/bors-ng/bors-ng) to automatically enforce this requirement without the PR author having to do it manually.. -All pull requests must be reviewed and approved by at least one MeiliSearch team -member. +
-#### Merge Style - -All pull requests are squashed and merged. We generally discourage large pull -requests that are over 300-500 lines of diff. If you would like to propose -a change that is larger we suggest coming onto our chat channel and -discuss it with one of our engineers. This way we can talk through the -solution and discuss if a change that large is even needed! This overall -will produce a quicker response to the change and likely produce code that -aligns better with our process. - -## Development - -### Setup - -See the [MeiliSearch Docs](https://docs.meilisearch.com/reference/features/installation.html) for how to set up a development environment. - -### Benchmarking & Profiling - -We do not yet do any benchmarking, nor have we formalised our profiling. If you'd like to work on this please get in touch! - -## Humans - -After making your change, you'll want to prepare it for MeiliSearch users (mostly humans). This usually entails updating documentation and announcing your feature. - -### Documentation - -Documentation is very important to MeiliSearch. All contributions that -alter user-facing behavior MUST include documentation changes. Please see -[GitHub.com/meilisearch/documentation](https://github.com/meilisearch/documentation) for more info. - -### Changelog - -Until we have guidelines in place, updating the [`Changelog`](/CHANGELOG.md) is solely the responsibility of MeiliSearch team members. +Thank you again for reading this through, we can not wait to begin to work with you if you made your way through this contributing guide ❤️