Cookbook Networking

Recreate PR #2112 from https://github.com/ocaml/ocaml.org/tree/cookbook-networking

.github/workflows/debug-ci.yml

@@ -0,0 +1,47 @@
+name: Debug CI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Dev and Debug Workflows
+
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - macos-latest
+          - ubuntu-latest
+        ocaml-compiler:
+          - ocaml-base-compiler.4.14.1
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+
+      - name: Use OCaml ${{ matrix.ocaml-compiler }}
+        uses: ocaml/setup-ocaml@v2
+        with:
+          ocaml-compiler: ${{ matrix.ocaml-compiler }}
+          dune-cache: ${{ matrix.os != 'macos-latest' }}
+          opam-repositories: |
+            pin: git+https://github.com/ocaml/opam-repository#8cc107f96e33a4601f7c39346eb19fbbe46486d3
+          opam-disable-sandboxing: true
+
+      - name: Install system dependencies (Linux)
+        run: sudo apt update && sudo apt-get install libev-dev libonig-dev libcurl4-openssl-dev
+        if: runner.os == 'Linux'
+
+      - name: Install system dependencies (macOS)
+        run: brew install libev openssl@3.3 # Openssl is a workaround for https://github.com/ocaml/opam-repository/issues/19676
+        if: runner.os == 'macOS'
+
+      - name: Install opam dependencies
+        run: opam install --deps-only .
+
+      - name: Build project
+        run: opam exec -- dune build
+

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # How to Contribute
 
-Welcome to OCaml.org's contributing guide. Thank you for taking the time to read it! Your help with OCaml.org is extremely welcome. We are particularly motivated to support new contributors and people who are looking to learn and develop their skills. If you get stuck, please don’t hesitate to [ask questions on discuss](https://discuss.ocaml.org/) or [raise an issue](https://github.com/ocaml/ocaml.org/issues/new).
+Welcome to OCaml.org's contributing guide. Thank you for taking the time to read it! Your help with OCaml.org is extremely welcome. We are particularly motivated to support new contributors and people who are looking to learn and develop their skills. If you get stuck, please don’t hesitate to [ask questions on Discuss](https://discuss.ocaml.org/) or [raise an issue](https://github.com/ocaml/ocaml.org/issues/new).
 
-This guide documents the best way to contribute to the project when adding things listed below in Contributing Content. If you're looking for a guide on how to setup the project and suggest a change to the code, you can refer to our [HACKING](./HACKING.md) guide, which will also give instructions on how to rebuild the website, if necessary, when making changes.
+This guide documents the best way to contribute to the project when adding things listed below in Contributing Content. If you're looking for a guide on how to setup the project and suggest a change to the code, you can refer to our [HACKING](./HACKING.md) guide, which will also give instructions on how to rebuild the website when making changes, if necessary.
 
 - **Good First Issues**: if you are either new to the repository or still getting started with OCaml in general, issues marked as a `good first issue` are ideal.
 - **Suggesting Changes**: most of the site content is stored in the `data` directory as Markdown or YAML. To suggest a change or update this content, you can edit those files directly and rebuild the website, detailed in the [HACKING](./HACKING.md) guide. This will promote the content into their `.ml` counterparts. If you would like to suggest entirely new website content or code, please [open an issue](https://github.com/ocaml/ocaml.org/issues) to discuss it first.
@@ -33,13 +33,13 @@ The following sections give more details on how to contribute to each.
 
 ### <a name="images"></a>Adding Images
 
-Some of the data that can be contributed by users may include images or other media, for example, success stories, academic and industrial users, or books.
+Some of the data that can be contributed by users may include images or other media; e.g., success stories, academic and industrial users, or books.
 
 Images can be added to the corresponding subfolder in the `data/media/` folder.
 
-E.g. for adding a university logo associated with an academic institution, you have to add the image file to the `data/media/academic_institution/` folder.
+For example, to add a university logo associated with an academic institution, you have to add the image file to the `data/media/academic_institution/` folder.
 
-Videos or other media should not be added to the ocaml.org GitHub repository.
+Videos or other media should not be added to the OCaml.org GitHub repository.
 
 ### <a name="content-blog"></a>Add an RSS Feed to the Blog
 
@@ -58,13 +58,13 @@ Please, make sure your feed only contains articles about OCaml.
 
 #### Link Original Blog Post
 
-To contribute a link to your original blog post (under [OCaml Community Blog](https://ocaml.org/blog)), you can add a new Markdown file in [`data/planet/-individual_external_links/`](data/planet/-individual_external_links/).
+To contribute a link to your original blog post (under [OCaml Community Blog](https://ocaml.org/blog)), add a new Markdown file in [`data/planet/-individual_external_links/`](data/planet/-individual_external_links/).
 
-Create an `.md` file with the following header:
+Create a `.md` file with the following header:
 
 ```
 ---
-title: title of your self-hosted post here
+title: Title of Your Self-Hosted Post Here (title case)
 description: one-sentence description
 url: direct URL to your original blog post
 date: 2023-06-13  (this format)
@@ -82,7 +82,7 @@ To add a new entry to the job board, you can add it to [`data/jobs.yml`](data/jo
 
 Please make sure that the job involves mostly writing OCaml. Contributions to add jobs unrelated to OCaml, or where OCaml is a negligible part of the job, won't be accepted.
 
-If you notice that a job opportunity is outdated (e.g., already fulfilled or not open anymore), PRs to remove it are welcome as well.
+If you notice that a job opportunity is outdated (e.g., already fulfilled or not open anymore), we also welcome PRs to remove it.
 
 ### <a name="content-success-story"></a>Add a Success Story
 
@@ -97,46 +97,46 @@ The success stories should be structured in the following way:
 - The solution you implemented, which should describe the role OCaml played in solving the challenge
 - A post-mortem describing the results you had after implementing the solution
 
-You can read [Ahref's success story](https://ocaml.org/success-stories/peta-byte-scale-web-crawler) for an examplary success story.
+You can read [Ahref's Success Story](https://ocaml.org/success-stories/peta-byte-scale-web-crawler) for a good example.
 
 ### <a name="content-user"></a>Add an Academic or Industrial User
 
 > Contribute to the [Academic Users](https://ocaml.org/academic-users) and [Industrial Users](https://ocaml.org/industrial-users).
 
-You can add a new academic user by creating a new Markdown file in [data/industrial_users/](data/industrial_users/). For instance: [cryptosense.md](data/industrial_users/cryptosense.md).
+Add a new academic user by creating a new Markdown file in [data/industrial_users/](data/industrial_users/). For instance: [cryptosense.md](data/industrial_users/cryptosense.md).
 
 You can add a new industrial user by creating a new Markdown file in [data/academic_institutions/](data/academic_institutions). For instance: [cornell.md](data/academic_institutions/cornell.md).
 
 ### <a name="content-book"></a>Add a Book
 
 > Contribute to the [OCaml Books](https://ocaml.org/books).
 
-You can add a new OCaml book by creating a new Markdown file in [data/books/](data/books/). For instance: [ocaml-from-the-very-beginning.md](data/books/ocaml-from-the-very-beginning.md).
+Add a new OCaml book by creating a new Markdown file in [data/books/](data/books/). For instance: [ocaml-from-the-very-beginning.md](data/books/ocaml-from-the-very-beginning.md).
 
 ### <a name="content-cookbook"></a>Add a Recipe to the OCaml Cookbook
 
-The OCaml cookbook is a place where OCaml developers share how to solve common
+The OCaml Cookbook is a place where OCaml developers share how to solve common
 tasks in OCaml using packages from the OCaml ecosystem.
 
 Here are the steps to contribute a recipe for an existing task:
-* Find the task in the [data/cookbook/tasks.yml](data/cookbook/tasks.yml) file
-* Go to the task folder inside [data/cookbook/](data/cookbook/) which has the
-  same name as the task's `slug`
-* Create a `.ml` file containing the recipe and a Yaml header with metadata about
+* Find the task in the [data/cookbook/tasks.yml](data/cookbook/tasks.yml) file.
+* Go to the task folder inside [data/cookbook/](data/cookbook/) that has the
+  same name as the task's `slug`.
+* Create a `.ml` file containing the recipe and a YAML header with metadata about
   the recipe.
 
 If the recipe does not fit into any existing task, you also need to create a
 task. Add a `task:` entry in [data/cookbook/tasks.yml](data/cookbook/tasks.yml)
-file. Fields `title`, `description` and `slug` are mandatory. The task must be
+file. Fields `title`, `description`, and `slug` are mandatory. The task must be
 located under a relevant `category:` field.
 
-Finally, it is also possible to create and organize groups of tasks by creating
+Finally, it is also possible to create and organise groups of tasks by creating
 new categories. Categories are recursive and may have subcategories, which are
 full categories too. A task listed in
-[data/cookbook/tasks.yml](data/cookbook/tasks.yml) may have no recipes yet. The
-other way, it is not allowed to have a task folder in
-[data/cookbook/](data/cookbook/) which does not correspond to a task from the
-[data/cookbook/tasks.yml](data/cookbook/tasks.yml) file, it triggers a
+[data/cookbook/tasks.yml](data/cookbook/tasks.yml) may have no recipes yet. On the 
+other hand, it is not allowed to have a task folder in
+[data/cookbook/](data/cookbook/) that does not correspond to a task from the
+[data/cookbook/tasks.yml](data/cookbook/tasks.yml) file because it triggers a
 compilation error.
 
 Each recipe is a way to perform a task using a combination of open-source
@@ -148,7 +148,7 @@ libraries.
 
 You can add a new recurring event by adding it to the YAML file [data/events/recurring.yml](data/events/recurring.yml).
 
-### <a name="content-upcoming_event"></a> Add an Upcoming Event
+### <a name="content-upcoming_event"></a>Add an Upcoming Event
 
 > Contribute to the [Upcoming Event](https://ocaml.org/community).
 
@@ -161,25 +161,25 @@ The [OCaml Changelog](https://ocaml.org/changelog) is a feed of the latest relea
 - [The OCaml Compiler](https://github.com/ocaml/ocaml)
 - [OCaml Platform Tools](https://ocaml.org/docs/platform)
 
-Before a release of the above tools land on the `opam-repository`, the release manager of the project opens a pull request (PR) on OCaml.org with an announcement for the release.
+Before a release of the above tools land on the `opam-repository`, the project's release manager opens a pull request (PR) on OCaml.org with the release announcement.
 
-The announcement is proofread by the OCaml.org team, who will also suggest highlighting release features.
+This announcement is proofread by the OCaml.org team, who will also suggest highlighting release features.
 
-To contribute to a new release announcement or feature highlight, add a Markdown file in `data/changelog/`.
+To contribute a new release announcement or feature highlight, add a Markdown file in `data/changelog/`.
 
 ## Git and GitHub Workflow
 
 The preferred workflow for contributing to a repository is to fork the main repository on GitHub, clone, and develop on a new branch.
 
 If you aren't familiar with how to work with Github or would like to learn it, here is [a great tutorial](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github).
 
-Feel free to use any approach while creating a PR. Here are a few suggestions from the dev team:
+Feel free to use any approach while creating a PR. Here are a few suggestions from the Dev team:
 
 - If you are not sure whether your changes will be accepted or want to discuss the method before delving into it, please create an issue and ask.
 - Clone the repo locally (or continue editing directly in GitHub if the change is small). Checkout
   out the branch that you created.
 - Create a draft PR with a small initial commit. Here's how you can [create a draft pull request.](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
-- Continue developing and feel free to ask questions in the PR if you run into obstacles or uncertainty as you make changes
+- Continue developing and feel free to ask questions in the PR if you run into obstacles or uncertainty as you make changes.
 - Review your implementation according to the checks noted in the PR template.
 - Once you feel your branch is ready, change the PR status to "ready to review."
 - Consult the tasks noted in the PR template.

data/changelog/dune/2024-04-14-dune.3.15.1.md

@@ -0,0 +1,19 @@
+---
+title: Dune 3.15.1
+tags: [dune, platform]
+changelog: |
+   ### Fixed
+   
+   - Fix overflow in `sendfile` stubs (copy of large files could fail or end with
+     truncated files) (#10333, @tonyfettes)
+   
+   - Fix crash when a rule with a directory target is disabled with `enabled_if`
+     (#10382, fixes #10310, @gridbugs)
+   
+   - Melange: remove all restrictions around virtual libraries in Melange. They
+     may be used as otherwise in libraries and executables. (#10412, @anmonteiro)
+   
+   - Spawn: fix compatibility with RHEL7 (#10428, @emillon)
+---
+
+We just released version 3.15.1 with some bug fixes.

data/changelog/dune/2024-04-23-dune.3.15.2.md

@@ -0,0 +1,16 @@
+---
+title: Dune 3.15.2
+tags: [dune, platform]
+changelog: |
+   ### Fixed
+   
+   - If no directory targets are defined, then do not evaluate `enabled_if`
+     (#10442, @rgrinberg)
+   
+   - Fix a bug where Coq projects were being rebuilt from scratch each time the
+     dependency graph changed. (#10446, fixes #10149, @alizter)
+---
+
+We just released version 3.15.2 with some bug fixes.
+
+This one is particularly important for Coq users since it fixes a bug introduced in 3.13.0 that made incremental builds very slow.

data/changelog/ocaml/2024-05-02-ocaml-5.2.0.rc1.md

@@ -0,0 +1,54 @@
+---
+title: OCaml 5.2.0 - First Release Candidate
+description: First Release Candidate of OCaml 5.2.0
+tags: [ocaml]
+changelog: |
+  ## Changes since the second beta
+  
+  - [#13130](https://github.com/ocaml/ocaml/issues/13130): Minor fixes to `pprintast` for raw identifiers and local module open
+    syntax for types.
+    (Chet Murthy, review by Gabriel Scherer)
+  
+  - [#13100](https://github.com/ocaml/ocaml/issues/13100) Fix detection of `zstd` when compiling with `musl-gcc`
+    (David Allsopp, review by Samuel Hym)
+---
+
+
+The release of OCaml 5.2.0 is imminent.
+As a final step, we are publishing a release candidate to check that everything is in order before the release in the upcoming week(s).
+
+If you find any bugs, please report them on [OCaml's issue tracker](https://github.com/ocaml/ocaml/issues).
+
+Compared to the second beta, this release contains one small compiler-libs printer fix and one configuration tweak.
+
+The full change log for OCaml 5.2.0 is available [on
+GitHub](https://github.com/ocaml/ocaml/blob/5.2/Changes). A short summary of the
+changes since the second beta release is also available below.
+
+---
+## Installation Instructions
+
+The base compiler can be installed as an opam switch with the following commands on opam 2.1 and later:
+```bash
+opam update
+opam switch create 5.2.0~rc1
+```
+
+The source code for the release candidate is also directly available on:
+
+* [GitHub](https://github.com/ocaml/ocaml/archive/5.2.0-rc1.tar.gz)
+* [OCaml archives at Inria](https://caml.inria.fr/pub/distrib/ocaml-5.2/ocaml-5.2.0~rc1.tar.gz)
+
+### Fine-Tuned Compiler Configuration
+
+If you want to tweak the configuration of the compiler, you can switch to the option variant with:
+```bash
+opam update
+opam switch create <switch_name> ocaml-variants.5.2.0~rc1+options <option_list>
+```
+where `<option_list>` is a space-separated list of `ocaml-option-*` packages. For instance, for a `flambda` and `no-flat-float-array` switch:
+```bash
+opam switch create 5.2.0~rc1+flambda+nffa ocaml-variants.5.2.0~rc1+options ocaml-option-flambda ocaml-option-no-flat-float-array
+```
+
+All available options can be listed with `opam search ocaml-option`.

data/cookbook/deserialise-from-yaml/00-yaml.ml

@@ -9,7 +9,7 @@ packages:
   used_libraries:
   - ppx_deriving_yaml
 ---
-(* The syntax `{| ... |}` is a quoted string. *)
+(* This is the string we are deserializing into the types we define below. *)
 let yaml = {|
 french name: pâte sucrée
 ingredients:
@@ -30,16 +30,16 @@ steps:
 - add flour
 |}
 
-(* The `[@@deriving of_yaml]` attribute makes library `ppx_deriving_yaml` generate the function
-  ``ingredient_of_yaml : Yaml.value -> (ingredient, [> `Msg of string]) result``
+(* The `[@@deriving of_yaml]` attribute makes makes the ppx from the library `ppx_deriving_yaml`
+  generate the function ``ingredient_of_yaml : Yaml.value -> (ingredient, [> `Msg of string]) result``
   If both serialising and deserialising are needed, replace `of_yaml` by `yaml`. *)
 type ingredient = {
   name: string;
   weight: int;
 } [@@deriving of_yaml]
 
-(* The `[@@deriving of_yaml]` attribute makes library `ppx_deriving_yaml` generate the function
-  ``recipe_of_yaml : Yaml.value -> (ingredient, [> `Msg of string]) result``. *)
+(* The function ``recipe_of_yaml : Yaml.value -> (ingredient, [> `Msg of string]) result``
+   generated here internally uses `ingredient_of_yaml`. *)
 type recipe = {
   name: string; [@key "french name"]
   ingredients: ingredient list;

data/cookbook/deserialise-from-yaml/01-hl_yaml.ml

@@ -9,7 +9,7 @@ packages:
   used_libraries:
   - ppx_deriving_yojson
 ---
-(* The syntax `{| ... |}` is a quoted string. *)
+(* This is the string we are deserializing into the types we define below. *)
 let yaml = {|
 french name: pâte sucrée
 ingredients:
@@ -30,23 +30,23 @@ steps:
 - add flour
 |}
 
-(* The `[@@deriving of_yojson]` attribute makes library `ppx_deriving_yojson` generate the function
+(* The `[@@deriving of_yojson]` attribute makes the ppx from the library `ppx_deriving_yojson` generate the function
   `ingredient_of_yojson : Yojson.Safe.t -> (ingredient, string) result`.
   If both serialising and deserialising are needed, replace `of_yojson` by `yojson`. *)
 type ingredient = {
   name: string;
   weight: int;
 } [@@deriving of_yojson]
 
-(* The `[@@deriving of_yojson]` attribute makes library `ppx_deriving_yojson` generate the function
-  ``recipe_of_yojson : Yojson.Safe.t -> (ingredient, string) result``. *)
+(* The function ``recipe_of_yojson : Yojson.Safe.t -> (ingredient, string) result`` generated here internally uses
+  `ingredient_of_yojson`. *)
 type recipe = {
   name: string; [@key "french name"]
   ingredients: ingredient list;
   steps: string list;
 } [@@deriving of_yojson]
 
-(* Parsing receives conversion into record as an argument. *)
+(* `parse` takes a function that converts from `Yojson.Safe.t` into the desired record type as an argument. *)
 let pate_sucree =
   yaml
   |> Hl_yaml.Unix.parse ~of_yojson:recipe_of_yojson