Commit 81eb9d7a authored by Kilian Weishaupt's avatar Kilian Weishaupt
Browse files

Merge branch 'contributionguide/backwardscompatibility' into 'master'

[contributionguide] Description of backwards compatibility policy

Closes #818

See merge request !1906
parents 864f59de cf403003
......@@ -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,
......
......@@ -76,6 +76,22 @@ over the mailing list, or file an [issue](https://git.iws.uni-stuttgart.de/dumux
feature implementations open a [merge request](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/merge_requests)
or send us formatted patches.
Backwards Compatibility
=======================
For a detailed description of the backwards compatibility policy,
please see [contribution guidelines](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md).
Dumux Releases are split into major(e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3) releases.
Major releases are not required to maintain backwards compatibility (see below),
but would provide a detailed guide on how to update dependent modules.
For each minor release, maintaining backwards compatibility is strongly encouraged and recommended.
Despite the goal of maintaining backwards compatibility across minor releases,
for more complicated changes, this is decided upon on a case to case basis, due to limited developer resources.
In the case that implementing full backwards compatibility for an update is not feasible, or would require unreasonable resources,
the degree of backwards compatibility be decided by a vote in one of the monthly core developer meetings.
Major version update, 2.12 to 3.0
===================================
......
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