Future version incompatibility warning

[arkid15r]

This is a starting point for the discussion of holidays package future backward incompatibility.

This is a future version incompatibility warning from Python Holidays library v{version}
to inform you about an upcoming change in our API versioning strategy that may affect your
project's dependencies. Starting from version 1.0 onwards, we will be following a loose form of
Semantic Versioning (SemVer) to provide clearer communication regarding any potential breaking
changes.

This means that while we strive to maintain backward compatibility, there might be occasional
updates that introduce breaking changes to our API. To ensure the stability of your projects,
we highly recommend pinning the version of our API that you rely on. You can pin your current
holidays v0.x dependency (e.g., holidays=={version}) or limit it (e.g., holidays<1.0) in order to
avoid potentially unwanted upgrade to the version 1.0 when it's released (ETA 2024Q4 - 2025Q1).

If you have any questions or concerns regarding this change, please don't hesitate to reach out
to us via https://github.com/vacanza/python-holidays/discussions/1800.

There will be no action required for those who has already taken care of the version pinning (or limiting it to <1.0) or will have it done within the nearest 6 months. We're going to provide migration guides and assist with actual code changes for other open source projects that depend on holidays.

[Lukas0907]

Is there any way to acknowledge/disable the warning? It shows up in the warnings summary section of pytest.

[arkid15r]

Is there any way to acknowledge/disable the warning? It shows up in the warnings summary section of pytest.

Yes, you should be able to ignore it in a regular way.

Here is a general example for pyproject.toml configuration:

[tool.pytest.ini_options]
filterwarnings = [
    "ignore::DeprecationWarning:your_module",
    "ignore:some specific warning message:WarningCategory:your_module"
]

[arkid15r]

Please check if

[tool.pytest.ini_options]
filterwarnings = [
    "ignore::DeprecationWarning:holidays",
]

works for you

[Lukas0907]

I was actually thinking about an environment variable, similar to how SQLAlchemy handles warnings. But of course this works, thank you.

[arkid15r]

I was actually thinking about an environment variable, similar to how SQLAlchemy handles warnings. But of course this works, thank you.

PYTHONWARNINGS="ignore::DeprecationWarning:holidays"

[digiDevemon]

Does this upgrade mean that there will be a stable version? Where can I find more information about it?

[arkid15r]

Thanks for the question, @digiDevemon!

The main idea is to move on from v0 version and be able to follow the SemVer versioning convention:

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backward compatible manner
• PATCH version when you make backward compatible bug fixes

I'll update the warning with SemVer link.

[sneha14]

@arkid15r ,
Hi, thanks for the heads up on the upcoming changes! Will there be updated documentation available to help with the transition to version 1.0, especially for those who need to migrate their code? Thanks!

[arkid15r]

@arkid15r , Hi, thanks for the heads up on the upcoming changes! Will there be updated documentation available to help with the transition to version 1.0, especially for those who need to migrate their code? Thanks!

Hi @sneha14,
Yes the documentation will be updated accordingly and I also plan to create a migration guide with old/new approach examples for smoother transitioning.