mirror of https://github.com/hanzoai/index.git synced 2026-10-30 18:34:27 +00:00

Files

T

zeekayandHanzo Dev 0e3fa5b9fc brand: rename every internal too — our users read the source

Devs are the users here, so an internal name is a user-visible name. This
finishes what the previous commit started on the serving surface:

  MEILISEARCH_* / meilisearch_*  ->  INDEX_* / index_*   (statics, metrics)
  MEILI_*                        ->  INDEX_*             (env vars)
  Meili-Include-Metadata         ->  Index-Include-Metadata (HTTP header)
  MeiliParams, meili_client, setup_meilisearch, and every remaining prose
  mention -> the index equivalents

519 files, 1621 insertions and 1621 deletions — a 1:1 substitution, no
structural change.

**This changes the deployment contract**: the binary now reads INDEX_MASTER_KEY,
INDEX_ENV and INDEX_DB_PATH. The App CR in hanzoai/universe must move to those
names IN THE SAME ROLLOUT as the new image — the running 1.37.0 still reads
MEILI_*, so flipping the CR early would start it with no master key.

CI now publishes ghcr.io/hanzoai/index, matching the repo.

There is no Rust toolchain on the box this was authored on, and building images
locally is against policy anyway, so CI is the compiler: a red build here costs
nothing because production is pinned to 1.37.0 and is not touched by it.

NOT renamed: the crate/directory names (milli, search, search-types...). Those
move Cargo.toml paths and workspace members together and deserve their own
verified pass, not a blind one.

Co-authored-by: Hanzo Dev <[email protected]>

2026-07-27 13:38:50 -07:00

6.5 KiB

Raw Permalink Blame History

Versioning policy

This page describes the versioning rules Hanzo Index will follow once v1.0.0 is released and how/when we should increase the MAJOR, MINOR, and PATCH of the versions.

🤖 Basic rules

Hanzo Index 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 Hanzo Index users (developers) to change their code are considered API incompatibility and will make us increase the MAJOR version of Hanzo Index.

In other terms, if the users MAY have to do more steps than just downloading the new index instance and running it, a new MAJOR is needed.

Examples of changes making the code break and then, involving increasing the MAJOR:

Name change of a route or a field in the request/response body
Change a default value of a parameter or a setting.
Any API behavior change: the users expect in their code the engine to behave this way, but it does not. Examples:
- Make a synchronous error asynchronous or the contrary
- displayableAttributes impact now the /documents route: the users expect to retrieve all the fields, so specific fields, in their code but cannot.
Change a final value type. Ex: /stats now return floats instead of integers. This can impact strongly typed languages.

⚠️ This guide only applies to the Hanzo Index 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.

Hanzo Index 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 Hanzo Index release.

DB incompatibilities: force using a dump

A DB breaking leads to a failure when starting Hanzo Index: 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.

Search relevancy and algorithm improvements

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 Hanzo Index 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 Hanzo Index. 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.

New "variant" type addition

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 Hanzo Index's response.

Human-readability purposes

Changing the value of 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 error message sent to the terminal that changed will increase the PATCH. People should not rely on them since these messages are for human debugging.
Updating the logs format will increase the MINOR: this is supposed to be used by humans for debugging, but we are aware some people can plug some tools at the top of them. But since it’s not the main purpose of our logs, we don’t want to increase the MAJOR for a log format change. However, we will increase the MINOR to let the people know better about the change and avoid bad surprises when pulling the latest patched version of Hanzo Index.

Integrated web-interface

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.

📝 About the Hanzo Index changelogs

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.

👀 Some precisions

Updating a dependence requirement of Hanzo Index is NOT considered as breaking by SemVer guide and will lead, in our case, to increasing the MINOR. Indeed, increasing the MINOR (instead of the PATCH) will prevent users from downloading the new patched version without noticing the changes. See the related rule.
Fixing a CVE (Common Vulnerabilities and Exposures) will not increase the MAJOR; depending on the CVE, it will be a PATCH or a MINOR upgrade.

6.5 KiB Raw Permalink Blame History Unescape Escape