New 'revision' field and variable

Current state of things

In https://github.com/ocaml/opam-repository/issues/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>)

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: "[email protected]"
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 https://github.com/ocaml/opam-repository/issues/10531