-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Policies
Kate edited this page Mar 18, 2024
·
3 revisions
Disclaimer: The policies are currently being discussed for change in #23789 (linked Discuss post), please feel free to participate to this discussion.
The current policies are the following:
- In case of a mistake, reverting a PR is allowed if the revert happened reasonably soon after the merge (e.g. < 1 day), to make sure a minimal number of users have pulled the repository in a state where the PR was in.
- Packages that are irredeemably broken can be marked with
available: false - Packages whose author want inaccessible for security reasons can be marked with
available: false - Packages whose author want gone from opam-repository can make their case with a PR marking them with
available: false. If the package(s) in question are not used by any other packages the PR should be good to merge, otherwise, a case by case basis, at the discretion of the opam-repository maintainers, is applied. - Case by case basis
- Users should be able to rely on any versions that have ever been available without breakage.
- Users that use opam < 2.1.6 or opam < 2.2.0~beta2 on macOS can sometimes lack GNU patch. The default macOS patch command does not support removal of files and would make
opam updatefail.
2. Packages should not be modified in a way that makes it uninstallable with an existing and working setup
- Known security issues with a combination of dependencies
- Non-deterministic or hard to properly fix failures
- Case by case basis
- Users should be able to rely on any versions that have ever been available without breakage.
- Users should be able to keep the packages that they have installed if they are working fine.
- Case by case basis
- Packages providing very little utility (e.g. one module with just one function defined as a one liner) do not seem justified to go in opam-repository and take one of the available names and space in the git repository that every user has to download
- opam-repository is a curated package repository, we hope to provide useful packages for the large majority of OCaml users
- Case by case basis
- Being misled when installing a package is pretty frustrating for users.
- If a package has a compatible interface as another and users mixup their name often, it can become a security risk.
- Developers spending time on a software, to find a package with the same name exists in opam-repository already and was added with malicious intents by another person, would be extremely frustrating for the developer and confusing for users if the project had been publicly announced prior.
- Strict equality constraints with packages that live in the same source repository (
{= version}) are accepted (and even encouraged) if the maintainer in planning to publish all the packages in that repository at once everytime there is some change. While this leads to a number of packages that are the same as their previous versions, this simplifies releases for maintainers that are in those cases, and makes the link simpler between the tag in their source repository and the version number in opam-repository. - Early
<constraints are allowed if it is known for sure that the package will not be compatible with said upcoming version or to prevent likely runtime failures with a next major version for example. - Case by case basis
- Strict constraints (in particular
=and<=/<) make the user experience worse by disallowing the combination of several packages requiring different strict dependencies in the same opam switch. - Strict constraints also make the work of opam-repository maintainers harder by the sheer number of PR that would simply change the constraints of a package.
- Strict constraints also make testing of the opam ecosystem worse by not testing the new releases of packages against packages that might be compatible with them (reverse dependencies, aka. revdeps).
- It is prefered to use
>=over>when writing dependency constraints because it makes constraints easier to read in most cases and would include potential package revisions or point-releases. For example> "1.0.0"would also include a potential1.0.0-1revision in the future, and> "0.9"would also include a potential0.9.1release that might not exists at the moment and that might not include the fix you need. - It is prefered to use
<over<=when writing dependency constraints because it would ignore any revision packages. For example<= "1.0.0"would not take into account a potential1.0.0-1, and<= "0.9"would not take into account a potential0.9.1release.
- Packages that are linked with already existing suite of packages that have adopted this version scheme for historical reasons.
- Packages whose maintainers want/need to change the version scheme to a version number that would be below the latest available version. For example
sexplib.113.33.03was the latest version of that package before Jane Street decided to reset the version scheme for readability reason to0.9.0, however 0.9.0 < 113.33.03 so thevprefix is here to make sure the order of version is kept, as 0.9.0 < 113.33.03 < v0.9.0. See the opam manual section on version ordering for more details. - Case by case basis
- It is much easier for users to write version constraints if they don't have to second guess for each dependencies if the version number contains a
vprefix or not.
- Packages relating to the OCaml compiler
- Packages for whom
ocamlis historically a part of the name and not a simple suffix (e.g. ocamlfind, ocamlgraph, ocamldap, …) - Packages whose name without the prefix/suffix would evoke something else that might also be an opam package or lack context (e.g. ocaml-lsp-server, ocaml-manual, …)
- Case by case basis
- opam-repository is an OCaml focused repository, so while many projects' name start with
ocaml-or end with-ocaml, if all of their package name would also includeocamlit would quickly become fairly annoying and redundant for users.
- OCaml compilers and related packages related to a fast moving branch are exempt
- Case by case basis
- Maintaining the metadata for many developement packages would mean too much work for the opam-repository maintainers.
- The resulting package would be too brittle and would break easily
- On the user's side, such package would lack checksum and thus have to be redownloaded and kept uptodate, everytime they do
opam update
- Case by case basis
- opam-repository currently strives to make installation as lightweight as possible for users of those packages. If a package were to install dependencies that is only used by (for example) developers of said package, it would be detrimental to their user experience, by having to compile and install packages they're not going to use. Example of such packages are:
ocamlformat,merlin, …. Which are in 99% of cases only required when developing a package. For people who want to install developement dependencies however, opam 2.2 introduced thewith-dev-setupvariable.
- Case by case basis
- opam is a source based package manager, it is not currently designed to handle portable binary packages properly.
- As it currently stands adding a binary package would require the facilities to ensure compatibilities with subarchitectures (e.g. x86_64 v1, …) which we do not have.
- opam-repository currently strives to provide the same experience regardless of your platform. Binary package would go against that as each platform would have to be packaged separately, or downloaded all together and sort which one to use on site. Either of these solutions would make the user's experience worse and the maintainers life worse as well.
- Case by case basis
- opam-repository packages are expected to be able to install at any time. Packages have a checksum to verify there hasn't been any malicious or unexpected changes to the archive after downloading it. If the source archive were to be changed, everyone who tries to install it would only receive failures, and even if it was fixed in a subsequent PR, it would still break users who have not used
opam update.