archiving policy: please define "archiving" and "maintaining"

[mjambon]

Context: contributors of packages are being asked to add a field x-maintenance-intent to new opam files, referring to this document as a guide.

I would like to know what archiving and maintaining means in this context and I'm sure others will have the same question.

• For a programmer, archiving a project (e.g. a GitHub project) means it becomes read-only. In the context of opam-repository, released packages are already read-only, so what does it mean that they are archived? Do they become unavailable to users via the opam command? Please specify.
• I wonder if "maintained" is the negation of "archived" in this context. From the perspective of a software vendor, it means we'll make subsequent releases based off the given release, typically by incrementing the patch version i.e. X.Y.Z → X.Y.(Z+1). However, it is common for a vendor to only commit to security fixes and/or only for some window of time, possibly depending on the release identifier (LTS, even vs. odd number, etc.). Details on this would inform maintainers about what they're promising and users what to expect.

[filipeom]

For a programmer, archiving a project (e.g. a GitHub project) means it becomes read-only. In the context of opam-repository, released packages are already read-only, so what does it mean that they are archived? Do they become unavailable to users via the opam command? Please specify.

From my understanding, archiving a package means it is no longer available to opam users through the default remote. Instead, it is moved to a special opam-repository: https://github.com/ocaml/opam-repository-archive.

The criteria for archiving are met once none of these requirements are fulfilled:

opam-repository/governance/policies/archiving.md

Lines 7 to 14 in 8143977

	- Have available sources
	- Be installable (but not necessarily pass tests)
	- on at least one supported platform
	- with at least one recent compiler (currently, meaning 4.08+)
	- Be maintained, according to the metadata of the latest version:
	- `x-maintenance-intent: ["(latest)"]` means that only the latest version is maintained
	- No `x-maintenance-intent` field means (for now) that all versions are maintained
	- Other values are possible (see below for a full list)

I think the goal of archiving old, unmaintained, or broken packages is twofold. First, it prevents users from installing broken packages that do not compile. Secondly, it helps opam scale by making package solving faster and speeding up updates to the opam repository remote.

I think the README of the archive repo also makes this motivation explicit: https://github.com/ocaml/opam-repository-archive?tab=readme-ov-file#motivation.

I wonder if "maintained" is the negation of "archived" in this context.

If archiving means not meeting the above criteria, then I think you're correct in arguing that maintainability is the negation of being archived.

From the perspective of a software vendor, it means we'll make subsequent releases based off the given release, typically by incrementing the patch version i.e. X.Y.Z → X.Y.(Z+1). However, it is common for a vendor to only commit to security fixes and/or only for some window of time, possibly depending on the release identifier (LTS, even vs. odd number, etc.). Details on this would inform maintainers about what they're promising and users what to expect.

Regarding this, I think x-maintenance-intent is not intended for users, but rather for the opam-repository maintainers. It helps focus efforts on packages that people want to keep around. This allows opam-repo maintainers to patch the opam files of packages that don't compile on newer versions of the OCaml compiler or that have conflicts with other package versions.

Regardless, in my opinion, x-maintenance-intent is also a great way to make the maintenance status of packages explicit. For example, if you only support security fixes for the latest version of your software, you could write: ["(latest).(latest).(any)"]. This means users can decide whether to use said package depending on how the maintainer intends to maintain it.

Actionable Points

With all that said, I think the archiving document referenced already points to the motivation for archiving packages at the end: https://github.com/ocaml/opam-repository/wiki/Package-Archiving:-Plan. Maybe we could move the motivation section to the top of the document? Or perhaps link the "Motivation" section from the opam-repository-archive README before the "Summary"?