https://github.com/meilisearch/specifications
Track specification elaboration.
https://github.com/meilisearch/specifications
openapi-specification specification
Last synced: 5 months ago
JSON representation
Track specification elaboration.
- Host: GitHub
- URL: https://github.com/meilisearch/specifications
- Owner: meilisearch
- License: mit
- Archived: true
- Created: 2020-10-27T16:25:39.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-21T14:33:50.000Z (about 1 year ago)
- Last Synced: 2024-09-26T10:41:01.670Z (9 months ago)
- Topics: openapi-specification, specification
- Homepage: https://specs.meilisearch.com
- Size: 850 KB
- Stars: 17
- Watchers: 8
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
---
# ⚠️ Archived Repository
We now use public pages on Notion to describe engine feature usages.
---
# Specifications Workflow
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.
## Draft State: Create a new PR
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
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`.
> 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.
The [pull-request template](pull_request_template.md) must be filled in when the pull-request is created.
## Review State
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.
The PR must be tagged as `Ready For Review` to enter this stage.
To be validated, it must be reviewed and approved by peers, ideally:
- One person from the Engine team.
- One person from the Integration team.
- One person from the Documentation team.
## Merge State
To be merged, a specification pull-request should follow the given rules:
- 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.
---
# Release Worfklow
The following steps should happen the day a Meilisearch release is shipped:
- 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.
---
## Specification File Format
Meilisearch's feature specifications are made up of five sections, described below.
### 1. Summary
Summarize the specification with a short paragraph.
### 2. Motivation
Explain which use cases are supported.
### 3. Functional Specification
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).
- Describe the API resource and endpoints. (Methods, URL, query parameters, body definition, status code).
- Explain the feature through examples.
- List error cases.
### 4. Technical Details (Optional)
When needed, we recommend describing practical aspects of implementation, e.g. specific algorithmic choices. If none, fill the section body with "n/a".
### 5. Future Possibilities (Optional)
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".