docs: update compatibility guidance

[ltalirz]

Summary

Drafting an update of the Compatibility guide as requested by @mkhorton in
#2083 (comment)

Checklist

Work-in-progress pull requests are encouraged, but please put [WIP]
in the pull request title.

Before a pull request can be merged, the following items must be checked:

• Code is in the standard Python style. The easiest way to handle this
  is to run the following in the correct sequence on your local machine. Start with running
  black on your new code. This will automatically reformat
  your code to PEP8 conventions and removes most issues. Then run
  pycodestyle, followed by
  flake8.
• Docstrings have been added in the Google docstring format.
  Run pydocstyle on your code.
• Type annotations are highly encouraged. Run mypy to type check your code.
• Tests have been added for any new functionality or bug fixes.
• All linting and tests pass.

Note that the CI system will run all the above checks. But it will be much more efficient if you already fix most
errors prior to submitting the PR. It is highly recommended that you use the pre-commit hook provided in the pymatgen
repository. Simply cp pre-commit .git/hooks and a check will be run prior to allowing commits.

[shyuep]

I don't think the writeup is necessarily true. I don't want to give up calendar version just because we are temporarily doing semantic versioning due to the switch over to a namespace package. In future, it will still be calendar versioned.

I think a more important statement is that if you happen to just use pymatgen for its core classes, it really doesn't matter in most instances whether you are using v2018, 2019 or 2021 or 2022. None of the core classes have undergone any backwards incompatible changes in the past few years.

Those who work on the bleeding age of pymatgen will of course have to live with the nature of a research code, i.e., it is always changing!

[coveralls]

Coverage decreased (-0.7%) to 82.985% when pulling 29e873e on ltalirz:issue_2083_semver into 3786ba9 on materialsproject:master.

[ltalirz]

I don't think the writeup is necessarily true. I don't want to give up calendar version just because we are temporarily doing semantic versioning due to the switch over to a namespace package. In future, it will still be calendar versioned.

Oh, I see.

Sorry, I had understood you were going to follow the principle of incrementing the major version number upon breaking changes not just until 2022 but also going forward.

Feel free to disregard this PR then.

I think a more important statement is that if you happen to just use pymatgen for its core classes, it really doesn't matter in most instances whether you are using v2018, 2019 or 2021 or 2022. None of the core classes have undergone any backwards incompatible changes in the past few years.

Since you mention this, I went back through the aiida-core issue tracker looking for pymatgen-related issues from the last two years

aiidateam/aiida-core#3244
aiidateam/aiida-core#3297
aiidateam/aiida-core#3263
aiidateam/aiida-core#4339
aiidateam/aiida-core#4614
aiidateam/aiida-core#4687
aiidateam/aiida-core#4793

On closer inspection, you are right that most of these are not related to breaking changes. Most were caused by issues with the numpy dependency (which should hopefully be fixed now with the pyproject.toml) and other dependencies.
Only two were breaking changes - the species_and_occu and the recent removal of imports from the core.

All in all, I still think that for a tool like aiida it would still be useful if pymatgen was using semantic versioning...
but of course announcing them via warnings well in advance already helps as well.

[mkhorton]

Adding the species_and_occu example to the compatibility page may be a good idea though, if at least to give people a better idea of how often these changes have happened in the past.

[shyuep]

@ltalirz Thanks. I will merge this and update the doc to reflect what Matt suggested.

[shyuep]

@ltalirz I have clarified the compatibility doc based on your suggested edits. Thanks.