Please provide guidance on which version to use
From the README, it is very hard to tell which versions of ScalFMM (tags, branches or commits) are meant to be used in production by end-users.
The obvious choice, for most software projects, is to use the latest stable release. In the case of ScalFMM, the closest thing we have to a “stable release” would be a tag. The latest tag (V1.5.1), however, is already quite old (2018-04-11). More annoyingly, it suffers from several issues (e.g. #21 (closed) and #22 (closed)) which have long ago been fixed in the git repo.
For lack of a suitable tagged version, one may be tempted to use the tip of a branch. This comes with its own problems:
-
Unlike tags, branches are expected to evolve. For a software project relying on ScalFMM, selecting a ScalFMM branch would make the build irreproducible. This can be annoying, and is unacceptable in the context of CI testing.
-
There are 13 branches to choose from, and no documentation on the purpose of each of them. The README simply suggests to check out “requested_branch” (sic), which is unhelpful. It also links to a description of the GitLab Flow, which fails to shed much light: It describes concepts such as “environment branches” and “release branches” which do not map to ScalFMM branches in an obvious way.
-
One may try to guess the purpose of each branch by looking at its name, however,
-
release_1.5 seems the most promising: the closest to a “release branch” in the sense of the GitLab flow, yet it is one year older than the tag V1.5.1.
-
maintenance/scalfmm-1.5 and maintenance/scalfmm-2.0 are fresher, yet they do not get all the fixes relevant to them (e.g. 49a2145a), as would be expected for release branches.
-
even master does not get all the relevant fixes (again, 49a2145a).
-
The last option would be to select a specific commit, identified by its SHA1. This is not ideal, and the choice of what commit to use is not obvious.
Suggested solutions
The optimal solution would be to have releases tagged on a regular basis (v1.5.2, v1.5.3... v2.0.0...). Failing that, some guidance in the README about what branches are meant for which users would be very welcome.