Versioning strategy?

[BenjaminRodenberg]

We decided to have independent versioning for the python bindings and for precice. However, we currently name the application for the python bindings precice (see here), because we want to call import precice. This situation is a bit misleading, since we install (for example) precice version 2.0.0 with version 0.1.0 of the python bindings (that are called precice inside the python world).

How can we

1. have a consistent naming
2. that's not confusing the user and
3. allows us to independntly version precice and the python bindings?

[BenjaminRodenberg]

Strongly related #4, since we have to clear up our minds, before we upload the python bindings (and precice?) to PyPI.

[MakisH]

I think the important difference is that the package we install via pip is named e.g. precice-python-bindings, so that the user does not get the impression that they also install preCICE with it. This could then have its own package and bindings version.

The python module would then be called precice: these are two different things, and they can coexist.

Then, the getVersionInfo() should actually give the version of preCICE itself. A separate method could give the version of the bindings.

[BenjaminRodenberg]

Another strategy we might want to consider:

Use Identical version like for preCICE, but declare it an alpha release to make users aware that the interface is not yet stable. See https://www.python.org/dev/peps/pep-0440/#pre-releases.

Example: pyprecice 2.0.0a provides bindings for precice 2.0.0

[MakisH]

But this clearly means that it is not released 2.0.0, right? I guess this is fine, but it also assumes that nothing else is changing in the Python bindings themselves, they are completely static apart from the changes necessary to follow preCICE.

It also means that for preCICE 2.0.1 (if any), we will have to release pyprecice 2.0.1a, which may have no changes from pyprecice 2.0.0a.

[uekerman]

I am also getting second thoughts about our current versioning suggestion for the bindings.
Gertjan suggested today that we should follow at least the major version.

Otherwise, we always talk about preCICE v2.0 and then a user downloads the python bindings from pypi and doesn't find a 2.0. Highly confusing. Will a Python user even understand the difference between precice and pyprecice? I am not sure if other packages do this.

.. but it also assumes that nothing else is changing in the Python bindings themselves, they are completely static apart from the changes necessary to follow preCICE.

I guess we can assume this, yes, once the Python bindings are "ready". Until then we could increase an alpha counter. pyprecice 2.0.0.a1

[MakisH]

Gertjan suggested today that we should follow at least the major version.

It would be nice to be reflected. If we refer to the major version, we should also refer to the feature version: we may have additional API methods.

Otherwise, we always talk about preCICE v2.0 and then a user downloads the python bindings from pypi and doesn't find a 2.0. Highly confusing.

In principle, the user should not need to try and understand the versions. The package manager (e.g. pip) should know which versions of the bindings need which versions of preCICE. But indeed, it would be nice to be directly related.

I guess we can assume this, yes, once the Python bindings are "ready". Until then we could increase an alpha counter. pyprecice 2.0.0.a1

A mixed scheme would probably be nice. How about something like pyprecice 0.1.0_precice2.1? The first is the bindings version, the second the minimum preCICE version supported. Then a package manager can check for version >= 0.1.0, and the user can see that this refers to preCICE 2.1.x.

As I wrote in our discussion in the mailing list:

Similar for the adapters: I now want to change the configuration format of the OpenFOAM adapter, which will be a breaking change for the adapter, but independent of preCICE. I need to bump the major version of the adapter, but not mean anything about preCICE.

From a technical viewpoint, I think every different package (=different repository) should have its own version, increasing the major version if something breaks in its own layer. With this in mind:

• preCICE API changes from v1 to v2, then bindings get updated to follow it, and then also increase their version independently (e.g. v5 to v6). But since the python-bindings package depends on precice-core, we need to specify this in the package description / pip specifications.
• OpenFOAM adapter changes the config, increases from v0 to v1. preCICE API changes --> no change in the adapter version.

The users could get confused, but if the users don't need to select versions in the first place (but a package manager), then our problem is solved.

The difference I see between adapters and bindings, is that the bindings should be much less complicated and much more static (when they are ready). So, we don't necessarily need to follow the same principles as in the adapters.

I don't have much experience with versioning systems, so indeed, let's see what other projects are doing / ask experts.

[uekerman]

In principle, the user should not need to try and understand the versions. The package manager (e.g. pip) should know which versions of the bindings need which versions of preCICE. But indeed, it would be nice to be directly related

The whole idea of also installing preCICE with a package manager like pip might give further problems. Let's say you install the python binding and preCICE with pip locally to run Nutils. And you want to couple to OpenFOAM for which you installed preCICE from debian. What happens if both preCICE versions are not the same? 🔥

The difference I see between adapters and bindings, is that the bindings should be much less complicated and much more static (when they are ready). So, we don't necessarily need to follow the same principles as in the adapters.

Yes. Another difference between adapters and bindings are that for adapters users might understand why there are different versions. It's a different project which also depends on the OpenFOAM version etc. For bindings, it's not so easy to understand that they are different from preCICE.

[MakisH]

What happens if both preCICE versions are not the same? fire

Isn't this a more general issue, independent of the bindings? We also have it now, as one solver may already be built with a different preCICE version (even as a static library). In many cases, this actually works! 😄

[uekerman]

Isn't this a more general issue, independent of the bindings?

In principle yes, but not completely, because it means that we cannot let the package manager figure out the correct preCICE version for the bindings. The user has to do this. Ergo: we need sth human understandable.

We also have it now, as one solver may already be built with a different preCICE version (even as a static library). In many cases, this actually works!

If they use the same preCICE version, then yes. If they use different versions: 🔥
And I see also no way that we can support this in the future. Even MPI cannot do this! (btw we depend on MPI).

[MakisH]

Then it has just worked by accident some times that I forgot to relink CalculiX? 😉 I always thought it as a feature. They only need to exchange the same kind of messages with the same kind of method. Yes, when we changed from .address to precice-run I wouldn't expect that to work.

(yes, I always used TCP sockets in this context)

[fsimonis]

The versioning also offers post-release versions.
So another option is to keep the precice version identical and append a post version for the bindings.
2.0.0.post1

If we use this scheme we could even drop the patch version and only keep major an minor.
2.1.post2