Parcels versioning and deprecation policy

[VeckoTheGecko]

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.

[erikvansebille]

Yes, I like it!

[VeckoTheGecko]

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

Thinking of removing this line, and replacing with the following:

Deprecations of classes or modules between minor releases will be avoided, except in the instance where it is deemed to have little to no impact on the end user (e.g., if the class/module was mistakenly included in the Public API to begin with).

details if we really need to deprecate classes/modules

I found that its possible to have similar deprecation behaviour for classes, and we can also do the same for modules by renaming the module, and creating a dummy module file that raises warning in the module if people try import directly from it.

This gives us more flexibility :')

[VeckoTheGecko]

If you have feedback about these policies, please let us know. We can still update them before v3.1.0 is released.