Fixing a release strategy for the adapter

[IshaanDesai]

Description

When the adapter was ported from an internal GitLab at the University of Stuttgart, it was compatible with DuMux v3.6 and DUNE v2.8. The adapter v1.0.0 was released with these compatibility specifications. In the mean time, DuMux v3.7 and DUNE v2.9 have been released. The adapter examples are being modified to support DuMux v3.7 and DUNE v2.9 in #22. This breaks compatibility of the examples (if not of the adapter directly) with older DuMux and DUNE versions.

Even though the adapter itself is not modified, the question arises whether or not to release a new version of the adapter for every new version of DuMux and DUNE. It is clear that DuMux does not maintain backward compatibility for minor versions v3.6 --> v3.7, hence some sort of release or tag creation of the adapter would be good. One idea would be to release minor version updates of the adapter for every minor version update of DuMux. Or is it not wise to link the releasing of an adapter to the releasing of the solver?

[ajaust]

I guess that finding a good strategy is complicated.

Maybe having a new adapter release when large, many or important changes (fixes etc.) have been made could make sense. A new DuMuX version and compatibility fixed could be a reason for a new version. An important question here is also how many DuMuX version does one want to support? Some things could be fixed with preprocessor checks, but it gets ugly quickly.

I guess the question is also how one uses the versioning scheme of the adapter. I see a good chance that one might break the compatibility between adapter version on a somewhat regular basis.

Also... should the adapter examples lead to new versions? Maybe we should break the repository up and have the examples in a separate repository. I am not convinced, that every breaking release of DuMuX must lead to a breaking change in the adapter. At least so far the adapter has been rather loosely coupled to DuMuX' internals.

Do you know what the OpenFOAM adapter does?

Release documentation suggestion

Adapter version	Tested DuMuX version	Tested DUNE version	Tested preCICE version
1.0.0	>=3.5 up to <3.7	2.8.0	>= 2.0.0
1.1.0	>=3.5 up to <3.8	2.8.0	>= 2.0.0
2.0.0	>=3.7 up	2.9.0	>= 2.0.0
3.0.0	>=3.7 up	2.9.0	>= 3.0.0

This table assumes that the adapter version 1.1.0 can replace 1.0.0, but going from 1.0.0 to 2.0.0 is not a drop-in replacement due to changes in DuMuX. Version 3.0.0 is a bigger step again due to changes in preCICE. However, maybe the adapter may hide some implementation details such that a new preCICE version would not lead to a major release.

[IshaanDesai]

Thanks for your inputs @ajaust!

An important question here is also how many DuMuX version does one want to support?

I have no reference regarding this, perhaps @mathiskelm can shed more light.

Also... should the adapter examples lead to new versions? Maybe we should break the repository up and have the examples in a separate repository.

This is a good idea! Some of the examples can even potentially become tutorials. I will have a look on how feasible this is.

This table assumes that the adapter version 1.1.0 can replace 1.0.0, but going from 1.0.0 to 2.0.0 is not a drop-in replacement due to changes in DuMuX. Version 3.0.0 is a bigger step again due to changes in preCICE. However, maybe the adapter may hide some implementation details such that a new preCICE version would not lead to a major release.

This sounds very reasonable as this is how one would expect minor version releases and major version releases to work.

[mathiskelm]

I don't expect the adapter itself to break often due to DuMux updates, so one could support perhaps one major version without many preprocessor checks.

The examples will break more often and flooding them with preprocessor statements is bad for new users. It would be great to have easily accessible examples for whatever version of DuMux (and preCICE and the adapter) you are using. Not sure how nicely one can do this using tags without treating them as proper releases of the adapter? While the idea of migrating the examples to preCICE tutorials sounds nice for many reasons, this would probably be easier/nicer to do in this/a separate repository specific to the adapter.

[uekerman]

I think it is a good idea to look how the OpenFOAM adapter does this and follow the example:

• Break up adapter and examples. Having the example in the preCICE tutorials would be nice, but is no requirement. They could also be somewhere else.
• Don't couple the versioning of the adapter to neither DuMuX, nor preCICE; especially when the interface between adapter and DuMuX is rather stable. Simply clearly document the dependencies.
  • v0.1 of the adapter has as dependencies: DuMuX (3.5 or 3.6), DUNE (2.8.0), preCICE (2.*)
  • The examples work with: DuMuX-preCICE adapter (0.1), DuMuX (...), ...
• Don't strictly couple the release strategy to any dependencies. Release a new version of the adapter when there is something to release. Only if you really rely on the newest DuMuX version for a certain use case, think about a pure compatibility release. (We also don't release a new preCICE version when there is new Boost version out, even if the Boost version is breaking)
• Support more versions through preprocessor flags if easy. If complicated, drop support of old versions. Users can always fall back to older versions of the adapter if needed.

[IshaanDesai]

Working on the feedback from @uekerman the first step would be to separate the examples from the adapter. I will have a look at the examples and see we can put them in a standalone repository, or make preCICE tutorials out of them.

Decoupling the adapter release strategy with that of DuMuX and preCICE is also a good idea. This will definitely make things easier.

[MakisH]

Regarding splitting the repository, I would upvote moving them to the preCICE tutorials. That repository already hosts examples, we don't need any other repository.

Unless there is a common versioning scheme for DuMuX-derived projects, I would stick to semantic versioning related to the "interface" of this project. For the OpenFOAM adapter, we defined it as the tutorial configuration files. If a new adapter version does not work with current tutorials because of configuration changes, then that would be a major version bump.

Regarding OpenFOAM versions, we just have a default and release version-specific archives for other versions. These are easy to get by rebasing version-specific branches, and there is no need for preprocessor checks.

Read more: https://precice.org/adapter-openfoam-get.html#what-does-the-adapter-version-mean

Related discussion: precice/openfoam-adapter#52

[stefano2734]

The infos of the releases should also be copied to readme.md here.