Commit cfbc2bda authored by Ned Coltman's avatar Ned Coltman
Browse files

[contributionguide] Description of backwards compatibility policy

parent 864f59de
......@@ -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,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment