documentation/versioning-policy.md
This page describes the versioning rules Meilisearch will follow once v1.0.0 is released and how/when we should increase the MAJOR, MINOR, and PATCH of the versions.
Meilisearch engine releases follow the SemVer rules, including the following basic ones:
🔥 Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards compatible manner
- PATCH version when you make backwards compatible bug fixes
Changes that MAY lead the Meilisearch users (developers) to change their code are considered API incompatibility and will make us increase the MAJOR version of Meilisearch.
In other terms, if the users MAY have to do more steps than just downloading the new Meilisearch instance and running it, a new MAJOR is needed.
Examples of changes making the code break and then, involving increasing the MAJOR:
displayableAttributes impact now the /documents route: the users expect to retrieve all the fields, so specific fields, in their code but cannot./stats now return floats instead of integers. This can impact strongly typed languages.⚠️ This guide only applies to the Meilisearch binary. Additional tools like SDKs and Docker images are out of the scope of this guide. However, we will ensure the changelogs are clear enough to inform users of the changes and their impacts.
Meilisearch is a search engine working with an internal database. It means some parts of the project can be really problematic to consider as breaking (and then leading to an increase of the MAJOR) without slowing down innovation.
Here is the list of the following exceptions of changes that will not lead to an increase in the MAJOR in Meilisearch release.
A DB breaking leads to a failure when starting Meilisearch: you need to use a dump.
We know this kind of failure requiring an additional step is the definition of “breaking” on the user side, but it’s really complicated to consider increasing a MAJOR for this. Indeed, since we don’t want to release a major version every two months and we also want to keep innovating simultaneously, increasing the MINOR is the best solution.
People would need to use dump sometimes between two MAJOR versions; for instance, this is something PostgreSQL does by asking their users to perform some manual actions between two MINOR releases.
Relevancy is the engine team job; we need to improve it every day, like performance. It will be really hard to improve the engine without allowing the team to change the relevancy algorithm. Same as for DB breaking, considering relevancy changes as breaking can really slow down innovation.
This way, changing the search relevancy, not the API behavior or fields, but the final relevancy result (like cropping algorithm, search algorithm, placeholder behavior, highlight behavior…) is not considered as a breaking change. Indeed, changing the relevancy behavior is not supposed to make the code fail since the final results of Meilisearch are only displayed, no matter the matched documents.
This kind of change will lead us to increase the MINOR to let the people know about the change and avoid non-expected changes when pulling the latest patched version of Meilisearch. Indeed, increasing the MINOR (instead of the PATCH) will prevent users from downloading the new patched version without noticing the changes.
🚨 Any change about the relevancy that is related to API usage, and thus, that may impact users to change their code (for instance changing the default matchingStrategy value) is not related to this specific section and would lead us to increase the MAJOR.
We don't consider breaking to add a new type to an already existing list of variant. For example, adding a new type of task, or a new type of error code.
We are aware some strongly typed language code bases could be impacted, and our recommendation is to handle the possibility of having an unknown type when deserializing Meilisearch's response.
message or link in error object will only increase the PATCH. The users should not refer to this field in their code since code and type exist in the same object.Any changes done to the integrated web interface are not considered breaking. The interface is considered an additional tool for test purposes, not for production.
All the changes, no matter if they are considered as breaking or not, if they are related to an algorithm change or not, will be announced in the changelogs.
The details of the change will depend on the impact on the users. For instance, giving too many details on really deep tech improvements can lead to some confusion on the user side.