From 36b406b762e7ac031596f41fd5a8de056d655245 Mon Sep 17 00:00:00 2001 From: Cuihtlauac Alvarado Date: Fri, 5 Jul 2024 08:33:13 +0200 Subject: [PATCH] Text editing (#2579) * line editing and formatting in adherence with style guide * line editing & formatting * mostly formatting * formatting to adhere to style guide * line editing & formatting to adhere to style guide * line editing & formatting to adhere to style guide * minor formatting change * titles are not markdown * Make title look the same as previous --------- Co-authored-by: Christine Rose Co-authored-by: Cuihtlauac ALVARADO --- HACKING.md | 65 ++++++----- .../changelog/merlin/2024-05-22-merlin-5.0.md | 12 +- data/changelog/odoc/2024-04-30-odoc-2.4.2.md | 2 +- .../opam/2021-02-08-opam-2-1-0-beta4.md | 18 +-- .../opam/2021-06-16-opam-2-1-0-rc.md | 102 ++++++++--------- data/changelog/opam/2021-08-04-opam-2-1-0.md | 108 +++++++++--------- data/changelog/opam/2021-12-08-opam-2-1-2.md | 2 +- 7 files changed, 154 insertions(+), 155 deletions(-) diff --git a/HACKING.md b/HACKING.md index 4ea4ab1313..e16c558d2d 100644 --- a/HACKING.md +++ b/HACKING.md @@ -2,46 +2,46 @@ ## Setup and Development -### Setting up the Project +### Setting Up the Project -Before starting to hack you need a properly configured development environment. Linux and macOS are supported and used daily by the core team. System dependencies include: +Before starting to hack, you need a properly configured development environment. Linux and macOS are supported and used daily by the core team. System dependencies include: * Libev: http://software.schmorp.de/pkg/libev.html * Oniguruma: https://github.com/kkos/oniguruma * OpenSSL: https://www.openssl.org/ * GNU Multiple Precision: https://gmplib.org/ -The project [`Dockerfile`](./Dockerfile) contains up-to-date system configuration instructions, as used to ship into production. It is written for the Alpine Linux distribution but is meant to be adapted to other environments such as Ubuntu, macOS+Homebrew or others. The GitHub workflow file [`.github/workflows/ci.yml`](.github/workflows/ci.yml) also contains useful commands for Ubuntu and macOS. Since ocaml.org is mostly written in OCaml, a properly configured OCaml development environment is also required, but is not detailed here. Although Docker is used to ship, it is not a requirement to begin hacking. Currently, ocaml.org doesn't yet compile using OCaml 5, version 4.14 of the language is used. It is possible to run workflow files in `.github/workflows` using the [nektos/act](https://github.com/nektos/act) tool. For instance, run the following command to run the CI checks run by GitHub on each pull request (where `ghghgh` is replace by an _ad-hoc_ GitHub token, see: https://github.com/nektos/act#github_token) +The project [`Dockerfile`](./Dockerfile) contains up-to-date system configuration instructions, as used to ship into production. It is written for the Alpine Linux distribution, but it is meant to be adapted to other environments such as Ubuntu, macOS+Homebrew, or others. The GitHub workflow file [`.github/workflows/ci.yml`](.github/workflows/ci.yml) also contains useful commands for Ubuntu and macOS. Since OCaml.org is mostly written in OCaml, a properly configured OCaml development environment is also required, but is not detailed here. Although Docker is used to ship, it is not a requirement to begin hacking. Currently, OCaml.org doesn't yet compile using OCaml 5; version 4.14 of the language is used. It is possible to run workflow files in `.github/workflows` using the [`nektos/act`](https://github.com/nektos/act) tool. For instance, the following command runs the CI checks through GitHub on each pull request (where `ghghgh` is replace by an _ad-hoc_ GitHub token, see: https://github.com/nektos/act#github_token) ``` act -s GITHUB_TOKEN=ghghgh .github/workflows/ci.yml -j build ``` -The `Makefile` contains many commands that can get you up and running, a typical workflow will be to clone the repository after forking it. +The Makefile contains many commands that can get you up and running. A typical workflow is to clone the repository after forking it. ``` -git clone https://github.com//ocaml.org.git -cd ocaml.org +git clone https://github.com//OCaml.org.git +cd OCaml.org ``` -Ensure you have `opam` installed. Opam will manage the OCaml compiler along with all of the OCaml packages needed to build and run the project. By this point we should all be using some Unix-like system (Linux, macOS, WSL2) so you should [run the opam install script](https://opam.ocaml.org/doc/Install.html#Binary-distribution). There are also manual instructions for people that don't want to run a script from the internet. We assume you are using `opam.2.1.0` or later which provides a cleaner, friendlier experience when installing system dependencies. +Ensure you have `opam` installed. Opam will manage the OCaml compiler along with all of the OCaml packages needed to build and run the project. By this point, we should all be using some Unix-like system (Linux, macOS, WSL2), so you should [run the opam install script](https://opam.OCaml.org/doc/Install.html#Binary-distribution). There are also manual instructions for people that don't want to run a script from the internet. We assume you are using `opam.2.1.0` or later, which provides a cleaner, friendlier experience when installing system dependencies. -With opam installed you can now initialise opam with `opam init`. Note in containers or WSL2 you will have to run `opam init --disable-sandboxing`. Opam might complain about some missing system dependencies like `unzip`, `cc` (a C compiler like `gcc`) etc. Make sure to install these before `opam init`. +With opam installed, you can now initialise opam with `opam init`. Note that in containers or WSL2, you will have to run `opam init --disable-sandboxing`. Opam might complain about some missing system dependencies like `unzip`, `cc` (a C compiler like `gcc`), etc. Make sure to install these before `opam init`. -Finally from the root of your project you can setup a [local opam switch](https://opam.ocaml.org/doc/Manual.html#Switches) and install the dependencies. There is a single `make` target to do just that. +Finally from the root of your project, you can setup a [local opam switch](https://opam.OCaml.org/doc/Manual.html#Switches) and install the dependencies. There is a single `make` target to do just that. ``` make switch ``` -If you don't want a local opam switch and are happy to install everything globally (in the opam sense) then you can just install the dependencies directly. +If you don't want a local opam switch and are happy to install everything globally (in the opam sense), then you can just install the dependencies directly. ``` make deps ``` -Opam will likely ask questions about installing system dependencies, for the project to work you will have to answer yes to installing these. +Opam will likely ask questions about installing system dependencies. Ror the project to work, you will have to answer yes to installing these. -### Running the server +### Running the Server After building the project, you can run the server with: @@ -57,7 +57,7 @@ make watch This will restart the server on filesystem changes. -### Running tests +### Running Tests You can run the unit test suite with: @@ -67,10 +67,10 @@ make test ### Building the Playground -The OCaml Playground is compiled separately from the rest of the server and the generated assets can be found in +The OCaml Playground is compiled separately from the rest of the server. The generated assets can be found in [`playground/asset/`](./playground/asset/). -You can build the playground from the root of the project, there is no need to move to the `./playground/` directory for the following commands. +You can build the playground from the root of the project. There is no need to move to the `./playground/` directory for the following commands. To regenerate the playground, you need to install the playground's dependencies first: @@ -78,35 +78,34 @@ To regenerate the playground, you need to install the playground's dependencies make deps -C playground ``` -After the dependencies have been installed, simply build the project to re-generate the JavaScript assets: +After the dependencies have been installed, simply build the project to regenerate the JavaScript assets: ``` make playground ``` -Once the compilation is complete and successuful, the newly generated assets have to be git committed -in ocaml.org and merged as a pull request. +Once the compilation is complete and successuful, commit the newly-generated assets in OCaml.org's Git repo and merge the pull request. ### Deploying Commits added on some branches are automatically deployed: -- `main` on . -- `staging` on . +- `main` on +- `staging` on -The deployment pipeline is managed in which listens to the `main` and `staging` branches and builds the site using the `Dockerfile` at the root of the project. You can monitor the state of each deployment on [`deploy.ci.ocaml.org`](https://deploy.ci.ocaml.org/?repo=ocaml/ocaml.org) +The deployment pipeline is managed in , which listens to the `main` and `staging` branches and builds the site using the `Dockerfile` at the project's root. You can monitor the state of each deployment on [`deploy.ci.OCaml.org`](https://deploy.ci.OCaml.org/?repo=ocaml/OCaml.org). -To test the deployment locally, you can run the following commands: +To test the deployment locally, run the following commands: ``` docker build -t ocamlorg . docker run -p 8080:8080 ocamlorg ``` -This will build the docker image and run a docker container with the port `8080` mapped to the HTTP server. +This will build the Docker image and run a Docker container with the port `8080` mapped to the HTTP server. -With the docker container running, you can visit the site at . +With the Docker container running, visit the site at . -The docker images automatically build from the `live` and `staging` branches, and are then pushed to Docker Hub: https://hub.docker.com/r/ocurrent/v3.ocaml.org-server +The Docker images automatically build from the `live` and `staging` branches. They are then pushed to Docker Hub: https://hub.docker.com/r/ocurrent/v3.OCaml.org-server. ### Staging Pull Requests @@ -118,16 +117,16 @@ to do so. For example, documentation PRs or new features where we need testing and feedback from the community will generally be live on `staging` for a while before they get merged. -### Managing dependencies +### Managing Dependencies -ocaml.org is using an Opam switch which is local and bound to a pinned commit in opam-repository. This is intended to protect the build from upstream regressions. The Opam repository is specified in three (3) places: +OCaml.org is using an opam switch that is local and bound to a pinned commit in `opam-repository`. This is intended to protect the build from upstream regressions. The opam repository is specified in three (3) places: ``` Dockerfile Makefile .github/workflows/*.yml ``` -When bringing up ocaml.org to a newer pin, the commit hash found it those files must be changed all at once. +When bringing up OCaml.org to a newer pin, the commit hash found it those files must be changed all at once. Once the opam repo pin is updated, the local switch must be updated using the following command: ```sh @@ -136,14 +135,14 @@ opam repo set-url pin git+https://github.com/ocaml/opam-repository# Where `` is the pinned hash specified in the files mentioned above. -Once this is done, you can do `opam update` and `opam upgrade`. If ocamlformat +Once this is done, you can run `opam update` and `opam upgrade`. If OCamlFormat was upgraded in the process, the files `.ocamlformat` and `.github/workflows/ci.yml` must be modified with the currently installed version -of ocamlformat. +of OCamlFormat. -## Repository structure +## Repository Structure -The following snippet describes the repository structure. +The following snippet describes the repository structure: ```text . @@ -151,7 +150,7 @@ The following snippet describes the repository structure. | The static assets served by the site. │ ├── data/ -| Data used by ocaml.org in Yaml and Markdown format. +| Data used by OCaml.org in Yaml and Markdown format. │ ├── playground/ │ The source and generated assets for the OCaml Playground diff --git a/data/changelog/merlin/2024-05-22-merlin-5.0.md b/data/changelog/merlin/2024-05-22-merlin-5.0.md index ed3cf0276c..f52fb86d06 100644 --- a/data/changelog/merlin/2024-05-22-merlin-5.0.md +++ b/data/changelog/merlin/2024-05-22-merlin-5.0.md @@ -4,18 +4,18 @@ tags: [merlin, platform] changelog: | + merlin binary - Support for OCaml 5.2 (#1757) - - destruct: Removal of residual patterns (#1737, fixes #1560) + - `destruct`: Removal of residual patterns (#1737, fixes #1560) - Do not erase fields' names when destructing punned record fields (#1734, fixes #1661) - Ignore SIGPIPE in the Merlin server process (#1746) - Fix lexing of quoted strings in comments (#1754, fixes #1753) - Improve cursor position detection in longidents (#1756) - - Addition of a merlin-lib.commands library which disassociates the - execution of commands from the new_protocol, from the binary, allowing + - Addition of a `merlin-lib.commands` library that disassociates the + execution of commands from the `new_protocol`, from the binary, allowing it to be invoked from other projects (#1758) - - New occurrences backend: Don't index occurrences when merlin.hide + - New occurrences backend: Don't index occurrences when `merlin.hide` attribute is present. (#1768) - - Use the new uid_to_decl table in 5.2's cmt files to get documentation. + - Use the new `uid_to_decl` table in 5.2's CMT files to get documentation. (#1773) @@ -25,4 +25,4 @@ We are pleased to announce the release of Merlin 5.0-502! This release brings official support for OCaml 5.2. Substantial backend changes were required to adapt to this release, especially for features such as occurrences and get-documentation. Do not hesitate to report any suspicious behavior in the [issue tracker](https://github.com/ocaml/merlin/issues)! -This release also fixes a handful of issues, two of them improving the behavior of Merlin's `destruct` feature. +This release also fixes a handful of issues, two of them improving the behaviour of Merlin's `destruct` feature. diff --git a/data/changelog/odoc/2024-04-30-odoc-2.4.2.md b/data/changelog/odoc/2024-04-30-odoc-2.4.2.md index 05225a9119..c9f05ba805 100644 --- a/data/changelog/odoc/2024-04-30-odoc-2.4.2.md +++ b/data/changelog/odoc/2024-04-30-odoc-2.4.2.md @@ -9,4 +9,4 @@ changelog: | - Fix issues #1066 and #1095 with extended opens (@jonludlam, #1082, #1100) --- -We've released Odoc 2.4.2 with compatibility with OCaml 5.2 and a few bug fixes. +We've released `odoc` 2.4.2 with OCaml 5.2 compatibility and a few bug fixes. diff --git a/data/changelog/opam/2021-02-08-opam-2-1-0-beta4.md b/data/changelog/opam/2021-02-08-opam-2-1-0-beta4.md index 3074be545d..c92c35cf0d 100644 --- a/data/changelog/opam/2021-02-08-opam-2-1-0-beta4.md +++ b/data/changelog/opam/2021-02-08-opam-2-1-0-beta4.md @@ -13,8 +13,8 @@ changelog: | * Set OPAMCLI=2.0 during package action commands [#4492 @kit-ty-kate] * Fix sandbox check on first `opam init` [#4370 @rjbou - fix #4368] * Print shell-appropriate eval command on `opam init` [#4427 @freevoid] - * Fix init script check in csh [#4482 @gahr] - * The stdout of `pre-` and `post-session` hooks is now propagated to the user [#4382 @AltGr - fix #4359] + * Fix `init` script check in csh [#4482 @gahr] + * The `stdout` of `pre-` and `post-session` hooks is now propagated to the user [#4382 @AltGr - fix #4359] * `post-install` hooks are now allowed to modify or remove installed files [#4388 @lefessan] * Add support for switch-specific pre/post sessions hooks [#4476 @rjbou - fix #4472] * Ensure we don't advertise upgrades to hidden versions [#4477 @AltGr - fix #4432] @@ -23,7 +23,7 @@ changelog: | * Fix `--update-invariant` when removing or changing package name [#4360 @AltGr - fix #4353] * Fix updates of the invariant with `--update-invariant` [#4431 @AltGr] * Fix cleanup of build dirs for version pinned packages [#4436 @rjbou - fix #4255] - * Fix opamfile format upgrade on pinning [#4366 @rjbou - fix #4365] + * Fix `opamfile` format upgrade on pinning [#4366 @rjbou - fix #4365] * Fix `pin --show` actually pinning [#4367 @rjbou - fix #4348] * When several pins are needed, do their fetching in parallel [#4399 @rjbou - fix #4315] * Don't cleanup VCS pin source directories [#4399 @rjbou] @@ -34,13 +34,13 @@ changelog: | * Skip loading the switch state for variable lookup when possible [#4428 @rjbou] * Fix package variables display when no config file is found [#4428 @rjbou] * Fix `opam option depext-bypass-=["XXX"]` [#4428 @rjbou] - * Lint: add a check that strings in filtered package formula are booleans or variables [#443 @rjbou - fix #4439] + * Lint: add a check that strings in filtered package formula are Booleans or variables [#443 @rjbou - fix #4439] * Fix handling of filename-encoded pkgname in opam files [#4401 @AltGr - fix ocaml-opam/opam-publish#107] * Don't recompile when modifying the package flags [#4477 @AltGr] * Add depext support for NetBSD and DragonFlyBSD [#4396 @kit-ty-kate] - * Fix depexts on OpenBSD, FreeBSD and Gentoo: Allow short names and full name paths for ports-based systems [#4396 @kit-ty-kate] + * Fix depexts on OpenBSD, FreeBSD, and Gentoo: Allow short names and full name paths for ports-based systems [#4396 @kit-ty-kate] * Handle the case where `os-family=ubuntu` as `os-family=debian` [#4441 @alan-j-hu] - * Update opam's opam files to 2.0 [#4371 @AltGr] + * Update opam's `opam` files to 2.0 [#4371 @AltGr] * Makefile: Add rule `custom-libinstall` for `opam-custom-install` use [#4401 @AltGr] * Use the archive caches when running `opam admin cache` [#4384 @AltGr - fix #4352] * Fix explosion of `opam admin check --cycles` on repositories with huge cliques [#4392 @AltGr] @@ -48,11 +48,11 @@ changelog: | * Fix missing conflict message when trying to remove required packages [#4362 @AltGr] * Fix the Z3 backend for upgrades [#4393 @AltGr] * Fix cases where opam would wrongly complain about action cycles [#4358 @AltGr - fix #4357] - * Fix permission denied fallback for openssl [#4449 @Blaisorblade - fix #4448] - * Add debug & verbose log for patch & subst applications [#4464 @rjbou - fix #4453] + * Fix permission denied fallback for `openssl` [#4449 @Blaisorblade - fix #4448] + * Add debug & verbose log for patch & `subst` applications [#4464 @rjbou - fix #4453] * Be more robust w.r.t. new caches updates when `--read-only` is not used [#4467 @AltGr - fix #4354] * Improved and extended tests [#4375 #4395 #4428 #4385 #4467 #4475 #4483 @emillon @rjbou @AltGr @freevoid @dra27] - * Switched to Github actions [#4463 @rjbou] + * Switched to GitHub actions [#4463 @rjbou] --- _Feedback on this post is welcomed on [Discuss](https://discuss.ocaml.org/t/ann-opam-2-1-0-beta4/7252)!_ diff --git a/data/changelog/opam/2021-06-16-opam-2-1-0-rc.md b/data/changelog/opam/2021-06-16-opam-2-1-0-rc.md index e483707833..77d2bc55e8 100644 --- a/data/changelog/opam/2021-06-16-opam-2-1-0-rc.md +++ b/data/changelog/opam/2021-06-16-opam-2-1-0-rc.md @@ -12,33 +12,33 @@ changelog: | * (+) Add `--no` [#4582 @rjbou] * (+) Add a `--with-0install-solver` option to the configure script to enable the 'builtin-0install' solver [#4646 @kit-ty-kate] - * Add default cli mechanism: deprecated options are accepted (in the major - version) if no cli is specified [#4575 @rjbou] - * Add `opam config` deprecated subcommands in the default cli + * Add default CLI mechanism: deprecated options are accepted (in the major + version) if no CLI is specified [#4575 @rjbou] + * Add `opam config` deprecated subcommands in the default CLI [#4575 @rjbou - fix #4503] - * Add cli versioning for opam environment variables [#4606 @rjbou] - * Add cli versioning for enums of flags with predefined enums [#4606 @rjbou] - * Clearer messages about using --cli and OPAMCLI [#4655 @dra27] + * Add CLI versioning for opam environment variables [#4606 @rjbou] + * Add CLI versioning for enums of flags with predefined enums [#4606 @rjbou] + * Clearer messages about using `--cli` and OPAMCLI [#4655 @dra27] * The options `--root` and `--switch` are now reflected in environment variables when building packages so that calls to `opam` during build access the correct root and switch [#4668 @LasseBlaauwbroek] - * Add cli versioning for enums of flags with predefined enums [#4626 @rjbou] + * Add CLI versioning for enums of flags with predefined enums [#4626 @rjbou] * Preprocess `--confirm-level` for plugins calls/install [#4694 @rjbou] * Ensure the symlink for a plugin is maintained on each invocation [#4621 @dra27 - partially fixes #4619] * Initialise environment variables for plugins call/install [#4582 @rjbou] - * Expect plugins to end in .exe on Windows [#4709 @dra27] + * Expect plugins to end in `.exe` on Windows [#4709 @dra27] * Introduce a `default-invariant` config field, restore the 2.0 semantics for `default-compiler` [#4607 @AltGr] * Fix default invariant with no system compiler [#4644 @AltGr - fix #4640] - * Perform an hard upgrade on intermediate roots, ie root from `2.1~alpha/beta`, + * Perform an hard upgrade on intermediate roots, i.e., root from `2.1~alpha/beta`, and keep a light upgrade from `2.0` [#4638 @rjbou] - * Send the 'opam root layout update' message to stderr [#4692 @AltGr] + * Send the 'opam root layout update' message to `stderr` [#4692 @AltGr] * If opam root is different from the binary, allow reading it and try to read in best effort mode [#4638 @rjbou - fix #4636] * Don't check opam system dependencies on reinit after a format upgrade [#4638 @rjbou] - * Fix `sys-ocaml-cc`, `sys-ocaml-arch` and `sys-ocaml-libc` when no system + * Fix `sys-ocaml-cc`, `sys-ocaml-arch`, and `sys-ocaml-libc` when no system compiler installed [#4706 @dra27] * Fix `Not_found` (config file) in config report [#4570 @rjbou] * Config report: Print variables of installed compilers and their (installed) @@ -52,7 +52,7 @@ changelog: | instead of the whole switch prefix when there are no `install:` instructions (and no preinstall commands) [#4494 @kit-ty-kate @rjbou; #4667 @dra27 - fix #4422] - * Scrub OPAM* environment variables added since 2.0 from package builds to + * Scrub opam* environment variables added since 2.0 from package builds to prevent warnings when a package calls opam [#4663 @dra27 - fix #4660] * Correct the message when more than one depext is missing [#4678 @dra27] * Only display one conflict message when they are all owing to identical @@ -66,26 +66,26 @@ changelog: | * On switch loading, if invariant is inferred and a write lock required, write the file [#4638 @rjbou] * Don't look for lock files for pin depends [#4511 @rjbou - fix #4505] - * Fetch sources when pinning an already pinned package with a different url + * Fetch sources when pinning an already-pinned package with a different URL when using working directory [#4542 @rjbou - fix #4484] * Don't ask for confirmation for pinning base packages (similarly makes no sense with 2.1 switch invariants) [#4571 @dra27] * Fix version pin source retrieving: mustn't error if archive opam file is malformed [#4580 @rjbou] * `opam list --silent` renamed to `--check` [#4595 @dra27 - fix #4323] - * Include doc field in opam-show [#4567 @dra27 - partially fix #4565] + * Include `doc` field in `opam-show` [#4567 @dra27 - partially fix #4565] * Fix `switch` global variable resolving [#4685 @rjbou - fix #4684] * Fix `hash` package variable resolving [#4687 @rjbou] - * Lint: Fix W59 & E60 for conf packages (no url required) + * Lint: Fix W59 & E60 for conf packages (no URL required) [#4550 @rjbou - fix #4549] - * Lint: Fix W59 & E60 with VCS urls, don't check upstream if url has VCS + * Lint: Fix W59 & E60 with VCS URLs, don't check upstream if URL has VCS backend [#4635 @rjbou] - * Lint: Add E67 checksum specified with non archive url [#4635 @rjbou] + * Lint: Add E67 checksum specified with non archive URL [#4635 @rjbou] * Lint: Disable subpath warning E63,W64 [#4638 @rjbou] * Lint: Fix manpage listing [#4708 @rjbou] - * Don't write lock file with `--read-only', `--safe`, and `--dryrun` + * Don't write lock file with `--read-only`, `--safe`, and `--dryrun` [#4562 @rjbou - fix #4320] - * Make `opam lock` consistent with `opam install`, on local pin always take + * Make `opam lock` consistent with `opam install`. On local pin, always take last opam file even if uncommitted [#4562 @rjbou - fix #4320] * Opam file: Fix `features` parser [#4507 @rjbou] * Opam file: Rename `hidden-version` to `avoid-version` [#4527 @dra27] @@ -108,94 +108,94 @@ changelog: | `OPAMNODEPEXTS`) [#4587 @AltGr] * Depext: Improve messages to hint that answering `no` doesn't abort installation [#4591 @AltGr] - * Depext: Add support for non-interactive mode in macports [#4676 @kit-ty-kate] - * Depext: Handling of packages of tagged repositories for alpine + * Depext: Add support for non-interactive mode in MacPorts [#4676 @kit-ty-kate] + * Depext: Handling of packages of tagged repositories for Alpine [#4700 @rjbou - fix #4670] * Depext: Clarify some `assume-depexts` related messages [#4671 @AltGr - partial fix #4662] - * Depext: Warn the user if epel-release is missing and unavailable depexts are + * Depext: Warn the user if `epel-release` is missing and unavailable, depexts are detected [#4679 @dra27 fix #4669] - * Depext: Ignore config yes automatic answering when asking confirmation to run + * Depext: Ignore `config yes` automatic answering when asking confirmation to run install commands [#4698 @rjbou - fix #4680] - * Sandbox: Fix the conflict with the environment variable name used by dune + * Sandbox: Fix the conflict with the environment variable name used by Dune [#4535 @smorimoto - fix ocaml/dune#4166] * Sandbox: Kill builds on Ctrl-C with bubblewrap [#4530 @kit-ty-kate - fix #4400] * Sandbox: Linux: mount existing TMPDIR read-only, re-bind `$TMPDIR` to a - separate tmpfs [#4589 @AltGr] + separate TMPFs [#4589 @AltGr] * Sandbox: Fix the sandbox check [#4589 @AltGr] * Sandbox: Fix sandbox script shell mistake that made `PWD` read-write on remove actions [#4589 @AltGr] - * Sandbox: Port bwrap improvements to sandbox_exec [#4589 @AltGr] - * Sandbox: Fix realpath use for macos, partial revert of #4589 [#4609 @AltGr] + * Sandbox: Port bwrap improvements to `sandbox_exec` [#4589 @AltGr] + * Sandbox: Fix `realpath` use for macOS, partial revert of #4589 [#4609 @AltGr] * Add missing shell quoting to support space and special shell characters in switch directory path [#4707 @kit-ty-kate] - * Rename `state.cache` to include the `OpamVersion.magic()` string. All .cache + * Rename `state.cache` to include the `OpamVersion.magic()` string. All `.cache` files are deleted if any cache file is written to, allowing multiple versions - of the library to co-exist without constantly regenerating it + of the library to coexist without constantly regenerating it [#4642 @dra27 - fix #4554] - * Fix Cudf preprocessing [#4534 #4627 @AltGr - fix #4624] + * Fix cuDF preprocessing [#4534 #4627 @AltGr - fix #4624] * Allow to upgrade to a hidden-version package if a hidden-version package is already installed [#4525 @kit-ty-kate] - * Add support for a few select criteria useful to CI to the 0install solver: + * Add support for a few select criteria useful to CI to the `0install` solver: `+count[version-lag,solution]` to always choose the oldest version available, `+removed` to not try to keep installed packages [#4631 @kit-ty-kate] - * Fix opam-devel's tests on platforms without openssl, GNU-diff and a - system-wide ocaml [#4500 @kit-ty-kate] - * Use dune to run reftests [#4376 @emillon] + * Fix `opam-devel`'s tests on platforms without OpenSSL, GNU-diff, and a + system-wide OCaml [#4500 @kit-ty-kate] + * Use Dune to run `reftests` [#4376 @emillon] * Restrict `extlib` and `dose` version [#4517 @kit-ty-kate] * Restrict to `opam-file-format.2.1.2` [#4495 @rjbou] * Require `opam-file-format.2.1.3+` in order to enforce `opam-version: "2.1"` as first non-comment line [#4639 @dra27 - fix #4394] - * Switch to newer version of MCCS (based on newer GLPK) for src_ext + * Switch to newer version of MCCS (based on newer GLPK) for `src_ext` [#4559 @AltGr] - * Bump dune version to 2.8.2 [#4592 @AltGr] - * Bump the minimal dune requirement to dune 1.11 [#4437 @dra27 @kit-ty-kate] + * Bump Dune version to 2.8.2 [#4592 @AltGr] + * Bump the minimal Dune requirement to Dune 1.11 [#4437 @dra27 @kit-ty-kate] * 4.12 compatibility [#4437 @dra27 @kit-ty-kate] * Cold compiler updated to 4.12 [#4616 @dra27] - * Fix build from source when a dune-project file is presented in the parent + * Fix build from source when a `dune-project` file is presented in the parent directory [#4545 @kit-ty-kate] - * Fix build from source when a dune-project file is presented in the parent + * Fix build from source when a `dune-project` file is presented in the parent directory [#4545 @kit-ty-kate - fix #4537] - * Fix opam-devel.install not to install two files called opam [#4664 @dra27] + * Fix `opam-devel.install` not to install two files called opam [#4664 @dra27] * Build release tags as non-dev versions, as for release tarballs [#4665 @dra27 - fix #4656] * Disable dev version for tests (needed for format upgrade test) [#4638 @rjbou] * Add a hint for missing `openssl` in `make cold` [#4702 @rjbou] - * Remove test field from opam-devel, they need the network [#4702 @rjbou] - * Update src_ext for Dune and MCCS [#4704 @dra27] - * Release scripts: switch to OCaml 4.10.2 by default, add macos/arm64 builds by + * Remove test field from `opam-devel`, they need the network [#4702 @rjbou] + * Update `src_ext` for Dune and MCCS [#4704 @dra27] + * Release scripts: switch to OCaml 4.10.2 by default, add macOS/ARM64 builds by default [#4559 @AltGr] - * Release scripts: add default cli version check on full archive build + * Release scripts: add default CLI version check on full archive build [#4575 @rjbou] * Arg: Generalise `mk_tristate_opt` to `mk_state_opt` [#4575 @rjbou] * Arg: Fix `mk_state_opt` and rename to `mk_enum_opt` [#4626 @rjbou] * Arg: Add `mk_enum_opt_all` for state flags that appears more than once [#4582 @rjbou] - * Fix `opam exec` on native Windows when calling cygwin executables + * Fix `opam exec` on native Windows when calling Cygwin executables [#4588 @AltGr] * Fix temporary file with a too long name causing errors on Windows [#4590 @AltGr] * CLI: Add flag deprecation and replacement helper [#4595 @rjbou] * Win32 Console: fix VT100 support [#3897 #4710 @dra27] * Tidied the opam files [#4620 @dra27] - * Externalise cli versioning tools from `OpamArg` into `OpamArgTools` + * Externalise CLI versioning tools from `OpamArg` into `OpamArgTools` [#4606 @rjbou] - * Each library defines its own environment variables, that fills the config + * Each library defines its own environment variables that fills the config record [#4606 @rjbou] - * Harden cygpath wrapper [#4625 @dra27] - * Reset the plugin symlinks when the root is upgraded + * Harden `cygpath` wrapper [#4625 @dra27] + * Reset the plugin `symlinks` when the root is upgraded [#4641 @dra27 - partial fix for #4619] * Formalise opam dev version detection with `OpamVersion.is_dev_version` [#4665 @dra27] * Add `OpamStd.String.is_prefix_of` [#4694 @rjbou @dra27] * Fix `OpamStd.Format.pretty_list`: `last` argument dropped if list contains more than 2 elements [#4694 @rjbou] - * Run the shell hooks with closed stdin (bash, zsh) [#4692 @AltGr] + * Run the shell hooks with closed `stdin` (bash, zsh) [#4692 @AltGr] * Improved and extended tests [#4376 #4504 #4545 #4612 #4668 #4612 #4634 #4672 #4638 #4702 #4697 #4697 @AltGr @dra27 @emillon @rjbou] - * Improve Github Actions + * Improve GitHub Actions [#4593 #4575 #4610 #4610 #4618 #4606 #4695 #4695 @AltGr @dra27 @rjbou] * Improve documentation [#4496 #4506 #4513 #4637 #4681 #4702 diff --git a/data/changelog/opam/2021-08-04-opam-2-1-0.md b/data/changelog/opam/2021-08-04-opam-2-1-0.md index aca1444ef0..4cf3705321 100644 --- a/data/changelog/opam/2021-08-04-opam-2-1-0.md +++ b/data/changelog/opam/2021-08-04-opam-2-1-0.md @@ -9,7 +9,7 @@ changelog: | * Fix 2.1~alpha2 to 2.1 format upgrade with reinit [#4750 #4756 @rjbou - fix #4748] * Fix bypass-check handling on reinit [#4750 @rjbou] * fish: fix deprecated redirection syntax `^` [#4736 @vzaliva] - * Bump src_exts and fix build compat with Dune 2.9.0 [#4754 @dra27] + * Bump `src_exts` and fix build compat with Dune 2.9.0 [#4754 @dra27] * Fix depext alpine tagged repositories handling [#4758 @rjbou] --- @@ -23,29 +23,29 @@ notes](https://github.com/ocaml/opam/releases) for the details), but here are a few highlights. -## What's new in opam 2.1? +## What's New in opam 2.1? -- Integration of system dependencies (formerly the opam-depext plugin), +- Integration of system dependencies (formerly the `opam-depext` plugin), increasing their reliability as it integrates the solving step -- Creation of lock files for reproducible installations (formerly the opam-lock +- Creation of lock files for reproducible installations (formerly the `opam-lock` plugin) - Switch invariants, replacing the "base packages" in opam 2.0 and allowing for easier compiler upgrades -- Improved options configuration (see the new `option` and expanded `var` sub-commands) +- Improved options configuration (see the new `option` and expanded `var` subcommands) - CLI versioning, allowing cleaner deprecations for opam now and also improvements to semantics in future without breaking backwards-compatibility -- opam root readability by newer and older versions, even if the format changed -- Performance improvements to opam-update, conflict messages, and many other +- `opam root` readability by newer and older versions, even if the format changed +- Performance improvements to `opam-update`, conflict messages, and many other areas -### Seamless integration of System dependencies handling (a.k.a. "depexts") +### Seamless Integration of System Dependencies Handling (a.k.a. "depexts") -opam has long included the ability to install system dependencies automatically +Opam has long included the ability to install system dependencies automatically via the [depext plugin](https://github.com/ocaml-opam/opam-depext). This plugin has been promoted to a native feature of opam 2.1.0 onwards, giving the following benefits: -- You no longer have to remember to run `opam depext`, opam always checks +- You no longer have to remember to run `opam depext`, as opam always checks depexts (there are options to disable this or automate it for CI use). Installation of an opam package in a CI system is now as easy as `opam install .`, without having to do the dance of `opam pin add -n/depext/install`. Just @@ -55,7 +55,7 @@ behaviour of opam in cases where the solver result is not stable. It was possible to get one package solution for the `opam depext` stage and a different solution for the `opam install` stage, resulting in some depexts missing. -- opam now has full knowledge of depexts, which means that packages can be +- Opam now has full knowledge of depexts, which means that packages can be automatically selected based on whether a system package is already installed. For example, if you have *neither* MariaDB nor MySQL dev libraries installed, `opam install mysql` will offer to install `conf-mysql` and `mysql`, but if you @@ -66,19 +66,19 @@ _Hint: You can set `OPAMCONFIRMLEVEL=unsafe-yes` or `--confirm-level=unsafe-yes` to launch non interactive system package commands._ -### opam lock files and reproducibility +### opam Lock Files and Reproducibility When opam was first released, it had the mission of gathering together scattered OCaml source code to build a [community repository](https://github.com/ocaml/opam-repository). As time marches on, the -size of the opam repository has grown tremendously, to over 3000 unique -packages with over 19500 unique versions. opam looks at all these packages and -is designed to solve for the best constraints for a given package, so that your +size of the opam repository has grown tremendously to over 3000 unique +packages with over 19500 unique versions. Opam looks at all these packages and +is designed to solve for the best constraints for a given package, so your project can keep up with releases of your dependencies. While this works well for libraries, we need a different strategy for projects that need to test and ship using a fixed set of dependencies. To satisfy this -use-case, opam 2.0.0 shipped with support for _using_ `project.opam.locked` +use case, opam 2.0.0 shipped with support for _using_ `project.opam.locked` files. These are normal opam files but with exact versions of dependencies. The lock file can be used as simply as `opam install . --locked` to have a reproducible package installation. @@ -99,24 +99,24 @@ export` new options, `--full` to have all packages metadata included, and `--freeze` to freeze all VCS to their current commit._ -### Switch invariants +### Switch Invariants In opam 2.0, when a switch is created the packages selected are put into the “base” of the switch. These packages are not normally considered for upgrade, in order to ease pressure on opam's solver. This was a much bigger concern -early on in opam 2.0's development, but is less of a problem with the default +early on in opam 2.0's development, but it is less of a problem with the default mccs solver. However, it's a problem for system compilers. opam would detect that your -system compiler version had changed, but be unable to upgrade the ocaml-system -package unless you went through a slightly convoluted process with +system compiler version had changed, but it's unable to upgrade the `ocaml-system` +package, unless you went through a slightly convoluted process with `--unlock-base`. In opam 2.1, base packages have been replaced by switch invariants. The switch invariant is a package formula which must be satisfied on every upgrade and install. All existing switches' base packages could just be expressed as -`package1 & package2 & package3` etc. but opam 2.1 recognises many existing -patterns and simplifies them, so in most cases the invariant will be +`package1 & package2 & package3`, etc., but opam 2.1 recognises many existing +patterns and simplifies them. Therefore, in most cases, the invariant will be `"ocaml-base-compiler" {= "4.11.1"}`, etc. This means that `opam switch create my_switch ocaml-system` now creates a _switch invariant_ of `"ocaml-system"` rather than a specific version of the `ocaml-system` package. If your system @@ -132,31 +132,31 @@ opam install utop ``` Creates a switch with OCaml 4.11.0 (the `--repos=` was just to select a version -of opam-repository from before 4.11.1 was released). Now issue: +of `opam-repository` from before 4.11.1 was released). Now issue: ``` opam repo set-url old git+https://github.com/ocaml/opam-repository opam upgrade ``` -and opam 2.1 will automatically offer to upgrade OCaml 4.11.1 along with a +Opam 2.1 will automatically offer to upgrade OCaml 4.11.1 along with a rebuild of the switch. There's not yet a clean CLI for specifying the formula, but we intend to iterate further on this with future opam releases so that -there is an easier way of saying “install OCaml 4.11.x”. +there is an easier way of saying “install OCaml 4.11.x." _Hint: You can set up a default invariant that will apply for all new switches, via a specific `opamrc`. The default one is `ocaml >= 4.05.0`_ -### Configuring opam from the command-line +### Configuring opam From the Command Line Configuring opam is not a simple task: you need to use an `opamrc` at init -stage, or hack global/switch config file, or use `opam config var` for +stage, hack `global/switch` config file, or use `opam config var` for additional variables. To ease that step, and permit a more consistent opam config tweaking, a new command was added : `opam option`. For example: @@ -165,11 +165,11 @@ For example: - `opam option jobs=6 --global` will set the number of parallel build jobs opam is allowed to run (along with the associated `jobs` variable) - `opam option depext-run-commands=false` disables the use of `sudo` for - handling system dependencies; it will be replaced by a prompt to run the + handling system dependencies. It will be replaced by a prompt to run the installation commands -- `opam option depext-bypass=m4 --global` bypass `m4` system package check +- `opam option depext-bypass=m4 --global` bypasses `m4` system package check globally, while `opam option depext-bypass=m4 --switch myswitch` will only - bypass it in the selected switch + bypass it in the selected switch. The command `opam var` is extended with the same format, acting on switch and global variables. @@ -181,39 +181,39 @@ default value._ ### CLI Versioning A new `--cli` switch was added to the first beta release, but it's only now -that it's being widely used. opam is a complex enough system that sometimes bug +that it's being widely used. Opam is a complex enough system that sometimes bug fixes need to change the semantics of some commands. For example: - `opam show --file` needed to change behaviour - The addition of new controls for setting global variables means that the `opam config` was becoming cluttered and some things want to move to `opam var` -- `opam switch install 4.11.1` still works in opam 2.0, but it's really an OPAM +- `opam switch install 4.11.1` still works in opam 2.0, but it's really an opam 1.2.2 syntax. Changing the CLI is exceptionally painful since it can break scripts and tools -which themselves need to drive `opam`. CLI versioning is our attempt to solve +which themselves need to drive opam. CLI versioning is our attempt to solve this. The feature is inspired by the `(lang dune ...)` stanza in `dune-project` -files which has allowed the Dune project to rename variables and alter +files, which has allowed the Dune project to rename variables and alter semantics without requiring every single package using Dune to upgrade their `dune` files on each release. Now you can specify which version of opam you expected the command to be run against. In day-to-day use of opam at the terminal, you wouldn't specify it, -and you'll get the latest version of the CLI. For example: `opam var --global` +so you'll get the latest version of the CLI. For example: `opam var --global` is the same as `opam var --cli=2.1 --global`. However, if you issue `opam var ---cli=2.0 --global`, you will told that `--global` was added in 2.1 and so is +--cli=2.0 --global`, you will have told it that `--global` was added in 2.1, so it's not available to you. You can see similar things with the renaming of `opam upgrade --unlock-base` to `opam upgrade --update-invariant`. -The intention is that `--cli` should be used in scripts, user guides (e.g. blog +The intention is that `--cli` should be used in scripts, user guides (e.g., blog posts), and in software which calls opam. The only decision you have to take is the _oldest_ version of opam which you need to support. If your script is using -a new opam 2.1 feature (for example `opam switch create --formula=`) then you +a new opam 2.1 feature (for example, `opam switch create --formula=`) then you simply don't support opam 2.0. If you need to support opam 2.0, then you can't -use `--formula` and should use `--packages` instead. opam 2.0 does not have the +use `--formula` and should use `--packages` instead. Opam 2.0 does not have the `--cli` option, so for opam 2.0 instead of `--cli=2.0` you should set the environment variable `OPAMCLI` to `2.0`. As with _all_ opam command line -switches, `OPAMCLI` is simply the equivalent of `--cli` which opam 2.1 will +switches, `OPAMCLI` is simply the equivalent of `--cli`, which opam 2.1 will pick-up but opam 2.0 will quietly ignore (and, as with other options, the command line takes precedence over the environment). @@ -223,8 +223,8 @@ command (or in your build system), you _must_ specify `--cli=2.1` if you're using new features. Since 2.1.0~rc2, CLI versioning applies to opam environment variables. The -previous behavior was to ignore unknown or wrongly set environment variable, -while now you will have a warning to let you know that the environment variable +previous behaviour was to ignore unknown or wrongly set environment variables. +Now you will have a warning to let you know that the environment variable won't be handled by this version of opam. To ensure not breaking compatibility of some widely used deprecated options, @@ -235,22 +235,22 @@ There's even more detail on this feature [in our wiki](https://github.com/ocaml/opam/wiki/Spec-for-opam-CLI-versioning). We're hoping that this feature will make it much easier in future releases for opam to make required changes and improvements to the CLI without breaking existing -set-ups and tools. +setups and tools. _Note: For opam libraries users, since 2.1 environment variable are no more loaded by the libraries, only by opam client. You need to load them explicitly._ -### opam root portability +### `opam root` Portability -opam root format changes during opam life-cycle, new field are added or -removed, new files are added ; an older opam version sometimes can no longer -read an upgraded or newly created opam root. opam root format has been updated +`opam root` format changes during opam's life cycle. New fields are added or +removed, and new files are added. An older opam version sometimes can no longer +read an upgraded or newly created `opam root`. `opam root` format has been updated to allow new versions of opam to indicate that the root may still be read by older versions of the opam libraries. A plugin compiled against the 2.0.9 opam libraries will therefore be able to read information about an opam 2.1 root (plugins and tools compiled against 2.0.8 are unable to load opam 2.1.0 roots). -It is a _read-only_ best effort access, any attempt to modify the opam root +It is a _read-only_ best effort access, any attempt to modify the `opam root` fails. _Hint: for opam libraries users, you can safely load states with @@ -258,7 +258,7 @@ _Hint: for opam libraries users, you can safely load states with load functions._ **Tremendous thanks to all involved people, who've developed, tested & retested, -helped with issue reports, comments, feedback...** +helped with issue reports, comments, feedback, etc...** -# Try it! +# Try It! In case you plan a possible rollback, you may want to first backup your `~/.opam` directory. @@ -281,7 +281,7 @@ The upgrade instructions are unchanged: bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh) --version 2.1.0" ``` - or download manually from [the Github "Releases" page](https://github.com/ocaml/opam/releases/tag/2.1.0) to your PATH. + or download manually from [the GitHub "Releases" page](https://github.com/ocaml/opam/releases/tag/2.1.0) to your PATH. 2. Or from source, manually: see the instructions in the [README](https://github.com/ocaml/opam/tree/2.1.0#compiling-this-repo). diff --git a/data/changelog/opam/2021-12-08-opam-2-1-2.md b/data/changelog/opam/2021-12-08-opam-2-1-2.md index 3e9142d64e..0684a13cd4 100644 --- a/data/changelog/opam/2021-12-08-opam-2-1-2.md +++ b/data/changelog/opam/2021-12-08-opam-2-1-2.md @@ -26,7 +26,7 @@ Opam installation instructions (unchanged): bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh) --version 2.1.2" ``` - or download manually from [the Github "Releases" page](https://github.com/ocaml/opam/releases/tag/2.1.2) to your PATH. In this case, don't forget to run `opam init --reinit -ni` to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script. + or download manually from [the GitHub "Releases" page](https://github.com/ocaml/opam/releases/tag/2.1.2) to your PATH. In this case, don't forget to run `opam init --reinit -ni` to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script. 2. From source, using opam: