Merge branch 'master' into release-melange-fetch-0.2.0

Author: davesnx

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: daily

.github/workflows/windows.yml

@@ -2,21 +2,28 @@ name: Windows CI
 on:
   push:
     branches:
-      - 'master'
+      - master
   pull_request:
 env:
   OPAMROOT: D:\opamroot
   OPAMSOLVERTIMEOUT: 120
+  MSYS: winsymlinks:native
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os:
           - windows-latest
+        windows_env:
+          - cygwin
+          - msys2
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout tree
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 2
 
       - name: Download install.ps1
         run: |
@@ -30,7 +37,14 @@ jobs:
           path: |
             D:\opam\bin
             D:\opamroot
-          key: ${{ runner.os }}-opam-${{ hashFiles('install.ps1') }}
+          key: ${{ runner.os }}-${{ matrix.windows_env }}-opam-${{ hashFiles('install.ps1') }}
+
+      - name: Add MSys2 to PATH and install prerequisites
+        if: matrix.windows_env == 'msys2'
+        run: |
+          "C:\msys64" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+          C:\msys64\usr\bin\pacman.exe --noconfirm -Syuu  # Core update (in case any core packages are outdated)
+          C:\msys64\usr\bin\pacman.exe --noconfirm -Syuu m4 make mingw-w64-i686-gcc mingw-w64-x86_64-gcc rsync unzip
 
       - name: Install opam
         if: steps.cache-opam.outputs.cache-hit != 'true'
@@ -44,7 +58,7 @@ jobs:
 
       - name: Init opam
         if: steps.cache-opam.outputs.cache-hit != 'true'
-        run: opam init --yes --no-setup .
+        run: opam init --yes --no-setup ${{ matrix.windows_env == 'msys2' && '--cygwin-local-install' || '' }} .
 
       - name: Restrict testing to available compilers
         if: steps.cache-opam.outputs.cache-hit != 'true'
@@ -60,10 +74,16 @@ jobs:
             D:\opamroot
           key: ${{ steps.cache-opam.outputs.cache-primary-key }}
 
+      - name: Print version information
+        run: |
+          opam --version
+          opam exec -- ocaml -version
+          opam var
+
       - name: Get changed files
         id: changed-files
         if: github.event_name != 'push'
-        uses: tj-actions/changed-files@v44
+        uses: tj-actions/changed-files@v47
 
       - name: List all changed packages
         id: changed-packages
@@ -96,7 +116,7 @@ jobs:
             opam install --color=always --confirm-level=unsafe-yes "$pkg"
             Write-Host "::endgroup::"
             switch ($LASTEXITCODE) {
-              0 { Break }
+              0 { Write-Host "`e[1;32m$pkg installed successfully`e[0m."; Break }
               5 { Write-Host "$pkg is not installable. `e[1;33mSkip`e[0m."; Break } # TODO: Remove when https://github.com/ocaml/opam/issues/6017 is fixed
               20 { Write-Host "$pkg is not installable. `e[1;33mSkip`e[0m."; Break }
               31 { Write-Host "`e[1;31m$pkg failed to build`e[0m."; $failed = $true; Break }
@@ -105,6 +125,6 @@ jobs:
             Write-Host
           }
           if ($failed) {
-            throw "build failed"
+            throw "One or more packages failed to build"
           }
           Exit

CONTRIBUTING.md

@@ -23,7 +23,6 @@ Each ones have their strengths and weaknesses. For example:
   * parses (and enforces a format, can be good or bad) for the changelog, to put it in the tag
   * creates the github release with that information
   * builds, run tests, lint
-  * uploads the documentation
   * creates and uploads a separate archive (also has an option to include the git submodules)
   * works only if your project is on GitHub
   * doesn’t support force-pushed tags
@@ -44,7 +43,7 @@ We'll cover each ones in the following subsections:
 
 First, make sure your project is using dune and is hosted on GitHub.
 Then, make sure you’ve forked opam-repository on GitHub. If not go to https://github.com/ocaml/opam-repository/fork
-Then, create a new file in `~/.config/dune/release.yml` with the content as indicated below, change `<username>` by your local username and `<github-user>` by your own github username:
+Then, create a new file in `~/.config/dune/release.yml` with the content as indicated below, change `<username>` by your local username and `<github-username>` by your own github username:
 ```
 remote: git@github.com:<github-username>/opam-repository.git
 local: /home/<username>/.cache/dune/opam-repository/
@@ -171,8 +170,8 @@ As an external contributor looking to patch a package, whose maintainer do not a
 Governance
 ----------
 
-The current points of contact and the full list of maintainers is available in [wiki/Governance](https://github.com/ocaml/opam-repository/wiki/Governance).
-Informations about the infrastructure is available in [wiki/Infrastructure-info](https://github.com/ocaml/opam-repository/wiki/Infrastructure-info).
+The current points of contact and the full list of maintainers is available in [./governance/README.md](./governance/README.md).
+Information about the infrastructure is available in [wiki/Infrastructure-info](https://github.com/ocaml/opam-repository/wiki/Infrastructure-info).
 
 Typically maintainers gather weekly to discuss ongoing topics, review PRs together and train maintainers in training.
 If you wish to help and become an opam-repository maintainer, you can send a message to the maintainers listed above and you will be invited to the next meeting in which they will explain how things work.
@@ -181,7 +180,7 @@ Policies
 --------
 
 Maintainers enforce a certain number of policies applied on packages in opam-repository.
-You can read about them in [wiki/Policies](https://github.com/ocaml/opam-repository/wiki/Policies).
+You can read about them in [./governance/policies/](./governance/policies/).
 
 How to deal with CI
 -------------------

governance/README.md

@@ -0,0 +1,42 @@
+# opam Repository Governance
+
+This directory holds documents codifying the governance of the opam package
+repository.
+
+## Policies
+
+See the [./policies/](./policies/) directory.
+
+## Maintenance
+
+### Main active maintainers
+
+You are very likely to interact with those maintainers when publishing your package. Don't
+hesitate to get in touch with them if you have questions about the publishing process,
+the CI results, or something else.
+
+- [@mseri](https://github.com/mseri)
+- [@raphael-proust](https://github.com/raphael-proust)
+- [@shonfeder](https://github.com/shonfeder)
+- [@jmid](https://github.com/jmid)
+- A few more occasional or in-training contributors
+
+To contact the maintainers in a more synchronous way you can join the [#opam-repository channel on the OCaml Discord](https://discord.gg/vDH7bMjjYW)
+
+### Full list of all maintainers
+
+- everyone listed above
+- [@avsm](https://github.com/avsm) (repository administrator)
+- [@samoht](https://github.com/samoht) (repository administrator)
+- [@dinosaure](https://github.com/dinosaure)
+- [@damiendoligez](https://github.com/damiendoligez)
+- [@djs55](https://github.com/djs55)
+- [@hcarty](https://github.com/hcarty)
+- [@yallop](https://github.com/yallop)
+- [@dra27](https://github.com/dra27)
+- [@smorimoto](https://github.com/smorimoto)
+- [@dbuenzli](https://github.com/dbuenzli) (triage)
+- [@axrwl](https://github.com/axrwl) (triage)
+- [@octachron](https://github.com/Octachron)
+- The opam developement team (for safe-keeping)
+- [@kit-ty-kate](https://github.com/kit-ty-kate) (former maintainer)

governance/policies/README.md

@@ -0,0 +1,179 @@
+# opam Repository Policies
+
+This document lists the explicit policies governing the maintenance and curation
+of the opam repository.
+
+*NOTE*: This policy is not static and will be updated as needed.
+
+<a name="policy-0"></a>
+## 0. Packages must meet the criteria for inclusion
+
+Packages in this repository should meet the [criteria for inclusion](./archiving.md#inclusion-criteria)
+enumerated in the [archiving policy](./archiving.md).
+
+## 1. Removal of packages should be avoided
+
+#### Exceptions:
+
+* Packages that no longer satisfy [policy 0](#policy-0).
+* 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
+
+#### Reasoning:
+
+* 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 update` fail.
+
+## 2. Packages should not be modified in a way that makes it uninstallable with an existing and working setup
+
+#### Exceptions:
+
+* Known security issues with a combination of dependencies
+* Non-deterministic or hard to properly fix failures
+* Case by case basis
+
+#### Reasoning:
+
+* 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.
+
+## 3. Packages should provide some sort of utility for users
+
+#### Exceptions:
+
+* Case by case basis
+
+#### Reasoning:
+
+* 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
+
+## 4. Namesquatting practices and misleading names are forbidden
+
+#### Exceptions:
+
+* Case by case basis
+
+#### Reasoning:
+
+* 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.
+
+## 5. Strict dependency constraints should be avoided (=, > or preventive upper bounds)
+
+#### Exceptions:
+
+* 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
+
+#### Reasoning:
+
+* 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 potential `1.0.0-1` revision in the future, and `> "0.9"` would also include a potential `0.9.1` release 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 potential `1.0.0-1`, and `<= "0.9"` would not take into account a potential `0.9.1` release.
+
+## 6. Version numbers should not have a v prefix (not v1.2.0 but 1.2.0)
+
+#### Exceptions:
+
+* 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.03` was the latest version of that package before Jane Street decided to reset the version scheme for readability reason to `0.9.0`, however 0.9.0 < 113.33.03 so the `v` prefix 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](https://opam.ocaml.org/doc/Manual.html#version-ordering) for more details.
+* Case by case basis
+
+#### Reasoning:
+
+* 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 `v` prefix or not.
+
+## 7. New package names should avoid the ocaml prefix/suffix
+
+#### Exceptions:
+
+* Packages relating to the OCaml compiler
+* Packages for whom `ocaml` is 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
+
+#### Reasoning:
+
+* 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 include `ocaml` it would quickly become fairly annoying and redundant for users.
+
+## 8. Developement packages (e.g. pointing to a git branch) are to be avoided
+
+#### Exceptions:
+
+* OCaml compilers and related packages related to a fast moving branch are exempt
+* Case by case basis
+
+#### Reasoning:
+
+* 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`
+
+## 9. Packages should only depend on packages they depend on at build time or runtime
+
+#### Exceptions:
+
+* Case by case basis
+
+#### Reasoning:
+
+* 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 the `with-dev-setup` variable.
+
+## 10. Binary packages should be avoided
+
+#### Exceptions:
+
+* Case by case basis
+
+#### Reasoning:
+
+* 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.
+
+## 11. Changes to a package's source archive are prohibited
+
+#### Exceptions:
+
+* Case by case basis
+
+#### Reasoning:
+
+* 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`.
+
+## 12. Extra-files are prohibited (patches in the `files/` subdirectory)
+
+The [extra-files field](https://opam.ocaml.org/doc/Manual.html#opamfield-extra-files) is not allowed in this repository. Please use [extra-source](https://opam.ocaml.org/doc/Manual.html#opamsection-extra-sources) if you need to include external files.
+
+#### Exceptions:
+
+* No exceptions
+
+#### Reasoning:
+
+* opam-repository is trying to use a minimal amount of files and size, thus any files not required are prohibited.
+* For cryptographic signing of the repository, not allowing extra-files reduces the complexity thereof.
+
+See the [announcement](https://discuss.ocaml.org/t/ann-opam-repository-policy-change-checksums-no-md5-and-no-extra-files/14720) and [discussion](https://github.com/ocaml/opam-repository/issues/25876) for further details.
+
+## 13. Weak hash algorithms (md5) are prohibited
+
+To prepare opam-repository for signing, adding only weak hash algorithms as checksums is prohibited.
+
+#### Exceptions:
+
+* No exceptions
+
+#### Reasoning:
+
+* Weak hash algorithms would induce that cryptographic signatures would be weak, or would need another set of checksums. This is costly and convolutes the repository.
+
+See the [announcement](https://discuss.ocaml.org/t/ann-opam-repository-policy-change-checksums-no-md5-and-no-extra-files/14720) and [discussion](https://github.com/ocaml/opam-repository/issues/25876) for further details.