Please stick to semantic versioning

[sergei-maertens]

As an open-source developer myself, I understand that time and resources are limited, and we do get to use this for free. I am creating this issue with the suggestion to pay more attention to which version numbers new releases get, and to help others find causes that may run into similar issues so that it's at least documented what happened.

I've been upgrading a complex project to Django 3.2, and one of the dependencies is django-relativedelta. We use some utilities in a shared library since django-relativedelta 1.0.5, and as it's an optional dependency of that shared library, there is some code in the form of:

try:
    from relativedeltafield import format_relativedelta, relativedelta
except ImportError:
    format_relativedelta = None
    relativedelta = None

Now, while upgrading to 1.1.2, tests started breaking on formatting, because we have a fallback path to format using iso8601 library with regular timedelta objects. This fallback path was incorrectly entered because the format_relativedelta import from __init__.py is no longer available as it was moved to the utils.py module. There was no public API specified through the __all__ attribute, nor were the utility functions marked as private with a leading underscore.

From version 1.0.5 through 1.1.1, the entire package was implemented in __init__.py, from 1.1.2 onwards, the package is restructured with broken existing imports.

It would've been far easier to spot this if a major version was published, or at the very least a new minor version with mention of the restructuring in the changelog and the effect it has on imports. So I'd like to suggest to:

• explicitly declare the public python API in the __all__ attribute in modules (__init__.py seems suitable for this).
• bump the major version on breaking changes, even if the broken imports are in a grey area
• document all changes made between versions, even if they are implementation details