Merge branch 'main' into release-v1.0.0

Author: gmourier

README.md

@@ -1,128 +1,80 @@
-# Specifications
+# Specifications Workflow
 
-This repository provides a template for creating **feature specifications** for Meilisearch. A feature specification is a written description of a feature that serves as a basis for development, design, and inter-team synchronization.
+This repository manages the specifications of the Meilisearch API. Specifications are meant to describe the expected behavior on a high level and point out identified corner cases.
 
-A **Merged specification** represents a Meilisearch feature that is implemented or ready to be.
+## Draft State: Create a new PR
 
----
-
-## Specification Workflow
-
-When a new feature or product is to be developed, a new pull request is created, and contributors are invited to discuss its content and propose suggestions. The goal of a feature specification is to define the expected behavior on a high level and point out corner cases that need to be addressed.
-
-The person in charge of the PR (the owner) is the person assigned to the PR. This allows for changing ownership. When the PR assignee changes, both new and old assignees should be notified.
-
-Meilisearch's feature specifications flow is made up of 5 states, described below.
-
-### Introduction State
-
-To start a new specification, it is recommended to write the first draft by filling in only the `Summary` and `Motivation` parts.
-
-The name of the spec file must follow the pattern: `PR_number-feature-name.md`. After the pull request creation, the owner should update the specification filename. For example, if PR number 12 is about facetting, its spec will be named `0012-facetting.md`.
-
-> Note that a pull request not strictly dealing about a specification conception will be tagged as `Not A Spec`.
-
-### Draft State
-
-Once the file is created with the two parts, `Summary` and `Motivation` filled in. It is time to create a draft PR. The PR should remain in draft state until the content is, according to the author, ready for comments. However, outsiders can make some recommendations, but these are more in the spirit of helping rather than suggesting changes.
-
-### Open State
-
-Once the specification is ready for comments in the owner's eyes, the owner can then switch the PR to open. At that time, it can be commented on, modified, challenged by these peers. If there is the slightest friction during this process, a discussion will be recommended offline within Meilisearch. The PR owner will organize this discussion, and at the end of this interview, the owner will make any necessary changes.
-
-At this step, the PR should be primarily tagged as `In Progress`.
-
-Note that if the pull request does not satisfy Open State conditions it will go back to the previous step above (***Draft State***).
+To start a new specification, a new branch must start
+- from `release-vX.X.X` if the related changes are already planned for the release `vX.X.X`
+- from `main` if you don't know in which release the changes will be integrated
 
-### Review State
+If a new specification file needs to be introduced, you must create a new file in [this folder](https://github.com/meilisearch/specifications/tree/main/text) following the pattern: `PR_number-feature-name.md`. e.g. if PR number 12 is about facetting, the newly introduced specification file will be named `0012-facetting.md`.
 
-The PR should now be tagged as `RFR (Ready For Review)` to enter this stage.
+> Note that a pull request not strictly dealing about a specification conception will be tagged as `Not A Spec`. e.g. A pull-request updating this file will be tagged with the `Not A Spec` label.
 
-To validate and merge the PR, it must be validated by at least three people.
+The [pull-request template](pull_request_template.md) must be filled in when the pull-request is created.
 
-- One person from the Integration team (preferably @curquiza).
-- One person from the Core team (preferably @Kerollmops).
-- One person from the DevRel team (preferably the person in charge of the documentation).
+## Review State
 
-Note that if the specification does not satisfy the merging conditions, it will go back to the previous step above (***Open State***) since it's lacking some pieces of information in the reviewer's eyes.
+It's up to the maintainers of this repository to decide when the PR is ready to be reviewed and which persons should review it.
 
-### Merge State
+The PR must be tagged as `Ready For Review` to enter this stage.
 
-The differents tracking-issues could be created on concerned repositories.
+To be validated, it must be reviewed and approved by peers, ideally:
 
-Created issues should:
-- `Spec Related` label has to be added to the issues.
-- Issues have to mention the spec in their description.
-- Issues must absolutely link to the PRs that resolve the spec, so that we can easily track them.
+- One person from the Integration team.
+- One person from the Core team.
+- One person from the Product team.
 
-In order to keep track of technical changes concerning the specification, delivery team should update the `Meilisearch Tracking-issues` part of the specification.
+## Merge State
 
-Once it's done, the specification is accepted and merged to the main branch.
+To be merged, a specification pull-request should follow the given rules:
 
-## Specification Revision
-
-Any Meilisearch's specification can change over time due to diverse factors. Sometimes related to change made on another specification concerning core engine code that could impact it, or simply product enhancement.
-
-In this precise case, a new PR is created and should follow the specification workflow described above.
+- It must be approved as described in the [Review State](#review-state) section.
+- The PR must point to the right `release-vX.X.X` branch.
+- It must be tagged with:
+  - A `vX.X.X` tag indicating in which release the described changes will be introduced.
+  - A `QX:YYYY` tag indicating in which quarter and year the described changes will be introduced.
+  - The `⚠ Breaking` tag, if breaking changes are introduced.
+  - The `Telemetry` tag, if telemetry changes are introduced.
+  - The `OpenAPI` tag, if the [open-api](open-api.yaml) specification will see changes introduced.
 
 ---
 
-## Specification Description and Interaction
-
-Meilisearch's feature specifications are made up of three sections, described below.
-
-### 1. Functional Specification
-
-This first section gives a high level overview of the feature. It should avoid technical language so that it can be understood by a general audience (think user-level). It is broken into five sub-sections, which are as follows:
-
-#### I. Summary
-
-One paragraph explaining the feature from the perspective of a user, e.g. "When I do X I want Y to happen because Z". This paragraph describes the problem and solution simply, without going into detail.
+# Release Worfklow
 
-#### II. Motivation
+The following steps should happen the day a Meilisearch release is shipped:
 
-Why develop this feature? What use cases does it support? What is the expected outcome? Add links to related issues and discussions.
+- Pull-requests describing changes for a release are squashed and merged into the corresponding `release-vX.X.X` branch.
+- `release-vX.X.X` is squashed and merged into `main`.
+- `open-api.yml` version is deployed on bump.sh.
 
-#### III. Additional Materials
-
-Discuss and include links to similar features in other tools or products. Share any concept art or visualizations that demonstrate what this proposal might look like in our search API (can be a screenshot of another tool, or a mockup made w/ dev tools). Consider any lessons that can be learned from outside implementations of the feature.
-
-This section is intended to provide readers of your pull request with a fuller picture of the proposed feature by comparing it with similar features in other tools and offering visual aids. If you don't have any examples of similar features being implemented elsewhere, that is fine—your ideas are interesting to us, whether they are brand new or adaptations from other tools.
-
-#### IV. Explanation
-
-Thoroughly explain your feature as if it was already implemented in Meilisearch and you were teaching another user how to use it. That generally means:
-
-- Introducing (and naming) any new concepts.
-- Explaining the feature largely through examples.
-- Noting the API for this feature, HTTP, CLI or config.
-- Explaining how the user should _think_ about the feature and how it will impact the way they use Meilisearch (provide concrete examples).
-- If applicable, provide sample error messages, deprecation warnings, or migration guidance.
-
-If the changes modify the HTTP API, provide a description of the method, URL, parameters, body, status code, errors, etc...
+---
 
-If it modifies the CLI, provide the env variable name, the argument name, and the description.
+## Specification File Format
 
-This section serves as a user-level guide and should resemble official documentation. Anything that the user may encounter while interacting with the feature should be presented here.
+Meilisearch's feature specifications are made up of five sections, described below.
 
-#### V. Impact on Documentation
+### 1. Summary
 
-If the feature requires additions or updates to the documentation, they should be noted here. It's the role of the documentation team to ensure this section of the feature specification is accurate.
+Summarize the specification with a short paragraph.
 
-#### VI. Impact on SDKs
+### 2. Motivation
 
-If the feature requires additions or updates to the SDks, they should be noted here. It's the role of the integration team to ensure this section of the feature specification is accurate.
+Explain which use cases are supported.
 
-### 2. Technical Aspects
+### 3. Functional Specification
 
-This section of the feature specification document has a much narrower audience: the developer(s) that will implement the feature. Its goal is to discuss and clarify how the feature will be developed and implemented when its not a trivial concern.
+This section gives a high level overview of the feature. It should avoid technical language so that it can be understood by a general audience (think user-level).
 
-> Internal technical teams may use this part to keep track of technical brainstorms, related proto code or basecode examples to clear the technical details of the specification.
+- Describe the API resource and endpoints. (Methods, URL, query parameters, body definition, status code).
+- Explain the feature through examples.
+- List error cases.
 
-At this time, the specification process is not enforcing a way to describe technical aspects. It can change in the future if we think that it is needed to ease the workflow of a specification creation.
+### 4. Technical Details (Optional)
 
-When writing technical details, we recommend describing practical aspects of implementation, e.g. interfaces, potential code problems, or specific algorithmic choices.
+When needed, we recommend describing practical aspects of implementation, e.g. specific algorithmic choices. If none, fill the section body with "n/a".
 
-### 3. Future Possibilities
+### 5. Future Possibilities (Optional)
 
-This last section includes any related topics or features which are not currently in Meilisearch and will not be added at this time, but which may affect the proposed feature in the future.
+This last section includes any related topics or features which are not currently in Meilisearch and will not be added now, but which may be explored in the future. If none, fill the section body with "n/a".