Proposal: New 'revision' field and variable

[kit-ty-kate]

Current state of things

In ocaml/opam-repository#10531, users are rightfully pointing that any changes made in opam-repository can break things.

The only workaround for users that we have is "try to find the git commit that broke things and opam repository set-url it", which isn't ideal.

The only workaround for opam-repository maintainers that we have is "try not to break things and if a new package is modified in a significant way, try to create a new <pkg>.<ver>-1 package with the changes", which is both not ideal and very annoying because:

• we have to draw the line of when to do a revision which is a fine line (doing a new revision package for every single modifications is not an option, we'd be nearing a trillion packages at this point..)
• it keeps the old unmodified versions around and polluting the repository with version of packages that should not be used by default
• adding a new revision package is not possible from the github interface and thus annoying to do for day to day maintainance
• the new revision will not be used by packages which uses = "1.0.1" or <= "1.0.1" type of constraints. We try to invite people to avoid them but some still go through (e.g. some tezos packages) or are advised (e.g. {= version})

The proposal

To fix all this issue I'm proposing that next time we break the opam file compatibility (most likely opam 3.0), a new revision field and variable would be added.
What would they do?

The new revision field would:

• Be a natural number
• Be set to 0 if not set
• Tell what is the current (major) revision of the package
• Would make any request to a <pkg>.<ver>-<revision> package an alias to <pkg>.<ver> (at the revision <revision>)
  • Other separators than - could be used to avoid breaking compatibility. e.g. :

This field would work in tandem with its variable counterpart.
The new revision variable would:

• Be available in every filter
• Be set to the current revision variable if not given
• Be set to any of the previous revisions if requested explicitly by opam install <pkg>.<ver>-<revision>

Example

opam-version: "2.0"
revision: "3"
maintainer: "pietro.abate@inria.fr"
authors: [...]
homepage: "http://www.mancoosi.org/software/"
bug-reports: "https://gitlab.com/irill/dose3/-/issues"
license: "LGPL-3.0-or-later with OCaml-LGPL-linking-exception"
dev-repo: "git+https://gitlab.com/irill/dose3.git"
build: [
  ["./configure"]
  [make "printconf"]
  [make] {revision < "2"}
  [make "libs" "apps"] {revision >= "2"}
]
install: [make "installlib"]
remove: [
  ["./configure"] {revision < "1"}
  [make "uninstalllib"] {revision < "1"}
]
depends: [
  "ocaml"
  "ocamlgraph" {>= "1.8.6" & < "2.0.0"}
  "cudf" {>= "0.7"}
  ("extlib" {>= "1.7.0" & < "1.7.8"} | "extlib-compat" {>= "1.7.0"})
  "re" {>= "1.2.2"}
  "ocamlbuild" {build}
  "cppo" {build & >= "1.1.2"}
]
conflicts: "dose"
patches: [
  "0001-Install-mli-cmx-etc.patch" {revision >= "1"}
  "0002-dont-make-printconf.patch" {revision >= "1"}
  "0003-Fix-for-ocaml-4.06.patch" {revision >= "1" & ocaml:version >= "4.06.0"}
  "0004-Add-unix-as-dependency-to-dose3.common-in-META.in.patch" {revision >= "3"}
]
synopsis: "Dose library (part of Mancoosi tools)"
url {
  src:
    "https://gforge.inria.fr/frs/download.php/file/36063/dose3-5.0.1.tar.gz"
  checksum: "md5=e7d4b1840383c6732f29a47c08ba5650"
}

Drawbacks

That I could think of, I think the main drawback from having this would be the build up of unmaintained bits in the opam files.
With time this might get out of hand.

---

Should partially fix ocaml/opam-repository#10531

[AltGr]

This could solve the problem; having one opam-file handling the multiple revisions is indeed a good idea. Here are a few drawbacks that I could see:

• the multiple-revision handling is written by hand: after a few revisions, the file will become hard to read.
• we'll need additional tooling to guarantee that a patch adding a new revision doesn't change the existing revisions — or better, to automatically generate the multi-revision opam file ?
• when computing the package universe for the solver, we need to decide what is visible exactly: only the last revision of every package ? That, plus what is installed/pinned ? Does (version-)pinning include the revision number ?

Re. ocaml/opam-repository#10531, we may need to differentiate between maintenance fixes (only changing opam metadata), and source fixes (changing the original tarball, adding patches, etc.). In the opam files, at the moment, there is no way to add filters to url.src, so changing that would be de facto excluded from this proposition, unless we extend the format further.