v0.27: Spec review and feedback

[guimachiavelli]

These are the specs for v0.27 (so far). Sorted from most to least feedback necessary.

1. Search API - Formatting Search Results specifications#120 — Cropping/Highlighting changes. Check for naming and clarity
2. Data Types - Add Nested Fields Support specifications#121 — Nested fields, a relatively big new feature. Check for clarity
3. Settings API - Typo Tolerance specifications#117 — New typo tolerance behaviour. Check for naming and clarity
4. Errors - Add variant for invalid_filter/invalid_sort when related settings are empty specifications#125 — Updates to two errors: invalid_sort and invalid_filter
5. Instance Options specifications#119 — 2 new instance options
6. Settings API - v0.26.0 state specifications#123 — A review of all existing index settings (unsure whether there's anything here for us)

Reference staging spec PR: meilisearch/specifications#129

[guimachiavelli]

Bonus spec!

7. Add --max-results-range / MEILI_MAX_RESULTS_RANGE instance option to prevent data scrapping specifications#131
   v0.27 is going to include a limit to the number of search results a single query can return. This was initially planned as an instance option, but due to limited resources will be implemented as a hardcoded value.

The issues has been closed, but there is still some discussion whether this is a 100% Good Idea™.

[guimachiavelli]

We can't assign reviewers in the spec repositories, so I'm listing each PR and the team member responsible for it:

1. Search API: @guimachiavelli
2. Nested fields: @dichotommy
3. Settings API: @maryamsulemani97
4. Error variants: @guimachiavelli
5. Instance options: @dichotommy

The remaining PRs do not need immediate action.

[guimachiavelli]

The following specs have been included under v0.27 since the original post:

1. Telemetry - Add missing "v" in the user-agent data specifications#136
2. Indexes API specifications#132
3. Stats API specifications#134
4. Documents API specifications#133
5. Misc - Update spec template according to our current usage specifications#127

The @meilisearch/docs-team won't review any of these, as they describe the current state of Meilisearch and do not propose new features.

[guimachiavelli]

Summary of specification review meeting (2022-04-11)

@guimachiavelli:

meilisearch/specifications#120

• Update Search API reference; more specifically, add the three new search options (highlightPreTag, highlightPostTag, cropMarker) to the Search Parameters section.

meilisearch/specifications#125

This spec only changes error messages (invalid_sort and invalid_filter), something not present in our Errors page. No action needed on our part.

@maryamsulemani97

meilisearch/specifications#117

• create a new API reference page
• create new section on learn/configuration/settings.md describing new index settings;
• create a mini-guide on learn/configuration/ (e.g. like learn/configuration/distinct.md);
• rename learn/advanced/typotolerance.md to something like Levenshtein algorithm;

@dichotommy

meilisearch/specifications#121

• update learn/advanced/datatypes.md with info on nested fields;
• update Index settings API reference of settings that accept attributes with a note/tip/etc block informing nested fields are supported;
• possibly update a few code samples so they include nested fields? Without any explanation, just to normalize (as in making common) nested field usage;

meilisearch/specifications#119

• update Instance options page with two new options (--max-indexing-memory, --max-indexing-threads)

[guimachiavelli]

Spec review finished, summary written.

Issue has been addressed.