diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ced855367b2e7c00a8eca0dc70f68c06f0df042..f3b2e82e3e45f1b2bffc3c9d7e42f1dfb7eb1328 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,68 @@ If you have any questions or complaints about this workflow of contributing to D * Merge requests get reviewed by at least one main developer. * If continuous integration (GitLabCI / BuildBot) is enabled for merge requests, the pipeline has to pass before merging anything to master. +## Backwards Compatibility +As a general rule, all changes added to the dumux master version should be made +such that: +* all tests and modules using dumux will still compile, and +* the user is warned at compile time of any interface changes. + +This can be done by masking removed methods with deprecation warnings: (example 1) + +```c++ +[[deprecated("This method will be removed after release (3.n). Use newMethod(x,y,z) instead!")]] +int oldMethod(const int x, const int y) const +{ return x + y; } + +int newMethod(const int x, const int y, const int z) const +{ return x + y > z ? x + y : z; } +``` + +or by adding intermediate method calls with warnings guarded by isValid +in the [`dumux/common/deprecated.hh`](dumux/common/deprecated.hh) header: (example 2) + +```c++ +// support old interface of the coolMethod() function on problems +template<class B> +struct HasNewCoolMethodIF +{ template<class A> auto operator()(A&& a) -> decltype( a.coolMethod(std::declval<const B>()) ) {} }; + +template<class A, class B + typename std::enable_if_t<!decltype(isValid(HasNewCoolMethodIF<B>()).template check<A>())::value, int> = 0> +auto DUNE_DEPRECATED_MSG("Use new coolMethod() interface that additionally receives + the object b! This will be removed after 3.n release") +coolMethod(const A a, const B b) +{ return a.coolMethod(); } + +template<class A, class B, + typename std::enable_if_t<decltype(isValid(HasNewCoolMethodIF<B>()).template check<A>())::value, int> = 0> +auto coolMethod(const A a, const B b) +{ return a.coolMethod(b); } + +``` +and replace the call with: + +``` c++ +Deprecated::template coolMethod(a, b); //TODO: Replace this after release 3.n + +``` + +There are other methods for deprecating old interfaces, please see [ (cppref/deprecated) ](https://en.cppreference.com/w/cpp/language/attributes/deprecated) for more information. + +In addition, please be sure to: + +* mark all deprecated interfaces with the release after which the deprecated interface will be removed, and +* add a detailed description of the changes made to the [changelog](CHANGELOG.md) + +**In some more complicated cases,** guaranteeing backwards compatibility for all possible +cases is not feasible, or would require enormous intrusive changes. In this case, we recommend you do the following: +1. Organize all changes neatly in a merge request. +2. Include a detailed description of the changes in the changelog. +3. Within the comments section of the merge request, mark one of the core developers, + and document the reasons why guaranteeing backwards compatibility would not be feasible, and which cases will likely be effected. +4. The core developers will decide if the changes and efforts are sufficient during the next monthly core developers meeting (aka DumuxDay). +5. Should your efforts be deemed sufficient, continue with the standard MR procedure. + ## Patches * Patches can be supplied via the mailing list,