[feat] Set a simple, independent version file for the current dynamic development and potential environment incompatibilities

[choinek]

• @pkarw I'm wondering if we shouldn't add some temporary VERSION file in which we will change the version when some important things change... and then during the application run, inform the user that he has an incompatible version and should check his .env files, because the user - even now - won't know that we added some configurations, etc., and his .env will be old. Of course, we should keep backward compatibility, but I think that we can't predict everything, and before we publish the official package, we should go with something like:

• Push to VERSION something like (...) 3 (I would go with int, it's not about semver here and we won't update it every time).
• Push to INCOMPATIBLE_CHANGES a simplified changelog which has a structure like:

--2--
(incompatible changes between 1 and 2)
--1--
(incompatible changes between non version and 1 version)

• After comparing, we will show messages to the user.
• Push to .env.example TEXT_EXTRACT_API_VERSION=3.
• Push to .env.localhost.example TEXT_EXTRACT_API_VERSION=3.
• In the run scripts, check:
  • If .env or .env.localhost exists, check both of them:
    • Missing TEXT_EXTRACT_API_VERSION -> old.
    • Lower than .repository_version -> old.
  • If not, then do nothing.

And in case of finding an old version:

• Ask the user to update his .env file based on .env.dist (we should change the name from example to dist because it's like variables that the user should acknowledge).
• Ask the user to clean up his .venv (usually done with make).
• Tell the user about possible changes.

[pkarw]

This is a great idea, however, I'd rather go with semver to not make a mess - I mean, we'll be releasing new versions of the API using semwer anyway, so it would be great to have it coherent.

The other option would be to check the os.getenv against keys defined in .env.dist to make sure all are set. I think it will provide us with the same value as version checking without the need to always remember to increment the version number, etc.

What do you think?

[choinek]

I'm not sure if Semantic Versioning (semver) will resolve my issue – semver operates at the application level (e.g., for endpoints) and needs to be updated every time a new version is released.

In this case, the versioning is strictly for the environment. It should only change when something significant related to the environment is modified. Additionally, the person updating it must review the changelog for context.

Although your suggestion of checking keys is a good one. In case of incompatibility (like what happened with the storage location), we can simply introduce a new environment variable – which might actually be an even better idea.