Change the way we display the compatible version of Meilisearch in our README's

[bidoubiwa]

Context

Currently, in our README's we provide the complete version of Meilisearch of which we know we are compatible.
Nonetheless, by doing so, we do not guarantee compatibility with latest patches.

For example

This package only guarantees the compatibility with the version v1.0.0 of Meilisearch.

When a v1.0.1 is released, we technically do not ensure compatibility.

Solution

The suggestion would be to avoid providing the patch version.

This package only guarantees the compatibility with the version v1.0.x of Meilisearch.

or

This package only guarantees the compatibility with the version v1.0 of Meilisearch.

Nonetheless, there is still an issue. What link to we provide to the user. In the example provided in the solution section of this issue, we do still use the URL to the latest patch version of Meilisearch. Which means that the user is still being redirected to that version and not the latest patch.

The solution to that would be to use the link to the latest release of Meilisearch and not a specific version:
https://github.com/meilisearch/meilisearch/releases/latest.

[curquiza]

I like this issue! Thanks for opening Charlotte!

I have two issues with the current sentence "this package only guarantees the compatibility with the version v1.0.x of Meilisearch.", but not related to the version part at all 😂

1. The compatibility definition

For me, the main issue, and source of confusion, is the definition you put on compatible with

Since Meilisearch is stable, when I read "this package is compatible with meilisearch v1.1" it means you can use every new feature added to Meilisearch with the SDK.

Example: if we add multi-index search + delete by filters in v1.1, you cannot write "compatible with Meiliseach v1.1" until every single feature present in v1.1 are integrated into the SDK -> will you really update the README once every feature are done? Remember, you will not implement every feature for every repository for each Meilisearch release

For me, the README needs to be clearer about what you mean with "compatible". For example, you can use it, but some features might be missing.

2. The "only"

Why only? When v1.1 with be released, the SDK will also be compatible with v1.0, not only v1.1 😄

[bidoubiwa]

You are right about both points.

The sentence in itself is not relevant anymore with v1 since we should be backward compatible, and there should not be any breaking so backward compatibility is implied. Nor are we clear about what compatibility means in terms of new feature implementation.

This package guarantees working with the version v1 of Meilisearch.

I'm not sure how we could inform the user which features are implemented and if we need to implement them all to update the version in the README.md.
Maybe we should have a table somewhere in the integration guide listing the features:

Features	JS	RUST	PHP
Typo tolerance	✅	✅	✅
Pagination Setting	✅	❌	✅
CSV documents	❌	❌	✅

And update the sentence accordingly:

This package guarantees working with the version v1 of Meilisearch. To know if a feature is implemented in the SDK, please refer to this table.

But this also raises a lot of questions. Should we list all the features, even those implemented in every SDK?

What do you think?

[curquiza]

I was even less ambitious, saying "the package is compatible, but some features might be missing, please check out this issue list to ensure the feature you need is present" and redirecting to the list of the issue labeled missing feature (for example)

The table can be tedious to maintain for you x30

But it's up to you integration team! I'm just here to report a potential confusing 😇

[brunoocasali]

I have done an answer, but I forgot to press submit! 😅

When a v1.0.1 is released, we technically do not ensure compatibility.

For me is just a formality. Since the patches did not introduce features in the engine (or in any software that follows the semver), the support is implicit in my point of view. In other words, if we say: v1.0.x or v1.0.0 or even v1.0 it means for semver that we support automatically also v1.0.86.

Today our statement is:

This package only guarantees the compatibility with the version v1.0.0 of Meilisearch.

It could be now:

This package guarantees compatibility with the version v1.0 of Meilisearch, but some of the features may not be present. Please check the issues for more info.

Then, for every new minor release, we just update version v1.1, version v1.4, and so on...
I liked the missing feature label, but we can use the good first issue + enhancement. Or we can adopt a new label anyway, no problem.

@alallema, please let us know your opinion too.

[brunoocasali]

@bidoubiwa I liked the table but just thinking about maintaining it in every repo gives me chills! Maybe we can automate something like that, based on the code-samples, and generate an HTML page for the docs website.

[alallema]

The sentence in itself is not relevant anymore with v1

I totally agree. I think the main point is just to change this sentence to something more relevant from now on.

For me, the main issue, and source of confusion, is the definition you put on compatible with

Yes, it is!

it means you can use every new feature added to Meilisearch with the SDK.

I disagree with that; for me, "compatible" means that it doesn't trigger any problem or conflict.

This package guarantees compatibility with the version v1.0 of Meilisearch, but some of the features may not be present. Please check the issues for more info.

Same as @brunoocasali, I like the missing feature! Also, I think it could be relevant now to have more specific READMEs for each SDK with features available or not

Why only?
Same, this sentence should be changed anyway.

For me, something like that would be ok because I consider it compatible if it works, but the missing feature should be updated each time!
This package guarantees compatibility with the version v1.0 of Meilisearch and later, but some of the features may not be present.

EDIT: About "have more specific READMEs for each SDK with features available or not." It should be decided in function of the Tier of the SDK

[brunoocasali]

If we look for the definition of compatibility in the dictionary:

It states exactly what @alallema said.

Because if a user keeps their meilisearch-php@v1 and never updates it anymore but keeps updating the Meilisearch engine to v1.1, v1.4, and v1.6, it should be working because this is the compatibility guarantee the user has by adopting libraries that adhere to the semver. Of course, they cannot expect the proper support for new features to be wrapped correctly.

If we put a table to help the users figure out quickly what feature is missing or not, it is a plus to me, but optional in this first iteration. Also, we can improve the @bidoubiwa's script based on the code-samples and then have a table for each SDK automatically.

---

So I still keep the proposal to use this message in the READMEs now:

This package guarantees compatibility with the version v1.0 of Meilisearch, but some of the features may not be present. Please check the issues for more info.

Are you comfortable with this decision @curquiza and @meilisearch/integration-team?

[curquiza]

TLDR; I agree with the sentence you suggested @brunoocasali 😄

Long answer, and my thought

I disagree with that; for me, "compatible" means that it doesn't trigger any problem or conflict.

If the feature is not present it definitely will trigger an error. The users will try to use multi_search() method, but the method doe not exist, so an error will be triggered.
But let's imagine it's a serious user, and this person reads the docs before using a new method (which is rare IMO, but let's imagine 😂): when I read the "to work with another" in the definition, I think the contrary then you: if the feature is not present, it means the software can not work together. Concretely, by following my example, if the multi_search() method (or whatever) is not present in the SDK, but it is in Meilisearch v1.1, the piece of software called "SDK" does not work with the piece of software called "Meilisearch v1.1"

I, however, understand your point of view. But the fact we disagree on this shows the potential confusion the users can have, and we need to be clear about our compatibility definition. So for me the sentence you suggested is good 👍

---

Another question is: are you going to update the version v1.0 of Meilisearch part of the sentence? From your point of view, which is "if it's not breaking, so it works, so it's compatible", you don't need to update it everytime because you will never have breaking until v2. No matter the SDK version, since you upgraded it to be compatible with Meilisearch v1.0, the SDK will always work with Meilisearch v1.X, no matter X.
So maybe any version v1.X of Meilisearch is better?

[brunoocasali]

Another question is: are you going to update the version v1.0 of Meilisearch part of the sentence? From your point of view, which is "if it's not breaking, so it works, so it's compatible", you don't need to update it everytime because you will never have breaking until v2. No matter the SDK version, since you upgraded it to be compatible with Meilisearch v1.0, the SDK will always work with Meilisearch v1.X, no matter X.
So maybe any version v1.X of Meilisearch is better?

The problem I see with the "x" is where should I redirect the user? Always to the first minor version available in this case the .0?

[brunoocasali]

If we are going to be very strict regarding compatibility, we have only two SDKs that are compatible with Meili, which are PHP and Python. Even Javascript is not compatible since it is missing this one: meilisearch/meilisearch-js#1061.

So are you sure we should be so strict when it comes to defining the "compatibility"?

[bidoubiwa]

The problem I see with the "x" is where should I redirect the user? Always to the first minor version available in this case the .0?

What do you mean with this? But until v2 we can use this one I suppose: https://github.com/meilisearch/meilisearch/releases/latest.

ABout this sentence

This package guarantees compatibility with the version v1.X of Meilisearch, but some of the features may not be present. Please check the issues for more info.

I like it, but I'll use v1.x as per the reasoning of @curquiza

From your point of view, which is "if it's not breaking, so it works, so it's compatible", you don't need to update it everytime because you will never have breaking until v2.