I propose for us to formalise our versioning and deprecation policy for Parcels. This formalisation allows us to form a social contract with users, clearly communicating what they can expect in terms of compatibility of their code with future versions of Parcels. This formalisation also sets guidelines for development of the project, bringing active consideration to backwards compatibility and deprecations.

Our deprecation and versioning policy will be mentioned in our documentation.

Proposed policy:

Parcels, as of v3.1.0, has adopted versioning and deprecation policies.

Versioning

Parcels mostly follows semantic versioning, where the version number (e.g., v2.1.0) is thought of as MAJOR.MINOR.PATCH.

MAJOR version for incompatible API changes
MINOR version for added functionality in a backward compatible manner
PATCH version for backward compatible bug fixes

Parcels doesn't implement strict backwards compatibility between minor versions. We may make small changes that deprecate elements of the codebase (e.g., an obscure parameter that is no longer needed). Such deprecations will follow our deprecation policy.

Note when conducting research we highly recommend documenting which version of Parcels (and other packages) you are using. This can be as easy as doing conda env export > environment.yml alongside your project code.

Deprecation policy

Deprecations in the Parcels codebase between minor releases will be handled using the following 6-month timeline:

• Functionality is marked for deprecation (e.g., in v2.1.0). This will include a warning to the user, instructions on how to update their scripts, and a note about when the feature will be removed. At this point the functionality still works as before.
• One minor release later (e.g., in v2.2.0), or at least 3 months later, the functionality will be replaced with NotImplementedError.
• One minor release later (e.g., in v2.3.0), or at least 3 months later, the functionality will be removed entirely.

These changes will be communicated in release notes.

Note that objects and modules won't be deprecated between minor releases.

Deprecations between major releases can be done at will as API changes are already expected.

If the community as a whole has any feedback on this, please comment below.