OCaml Weekly News

Previous Week Up Next Week

Hello

Here is the latest OCaml Weekly News, for the week of February 21 to 28, 2023.

Table of Contents

Looking for Ideas for the Package Overview Page on OCaml.org

Archive: https://discuss.ocaml.org/t/looking-for-ideas-for-the-package-overview-page-on-ocaml-org/11416/50

Continuing this thread, Sabine Schmaltz summarized

Ok, so that was quite a bit to digest. Here’s a summary:

1- Debate about package quality metrics

Having “last published” and publication date in general displayed on the page might interfere with the visibility of stable packages that do not need improvement.

Ideas for other metrics:

  • (manual) self-assessment of package author. (Code quality, performance, maintainability, evolution, version >= 1.0.0 etc.)
  • (manual) Maintenance-related tagging: signal the need for additional maintainers, signal that a package needs maintenance
  • (automated) Signal broken packages.
  • (automated) Metrics from external sourecs: e.g. GitHub Number of issues / pull requests / star count
    • Contrapoint: supporting all options, including popular open source self-hosted optionsis a huge work item, and choosing just a few is inherently unfair
  • (automated) Weekly download statistics

2- Debate about displaying or not displaying README / opam description / index.mld on package overview:

  • Since README is publicly displayed on GitHub/GitLab etc, many people currently use it as a “public landing page” of the package.
    • Essentially, these other services encourage writing README in a certain way - in order to establish proper context within that other service
  • Challenge: Ideally, package authors should not have to repeat the same info in several places.
  • Aspects to consider wrt README:
    • different renderers on different sites (e.g. GitLab, GitHub, SourceHut, Pygments, etc.) support different markdown features
    • Nowadays more and more READMEs contain images or even videos, as well as tons of badges
  • Ideas:
    • Show a collapsible README on package overview
    • Instead of rendering README on package overview: add a link to the README (but where to, to the hosted repository or to ocaml.org’s rendition of README?)
  • Index.mld and other .mld files could be displayed instead of README. Additionally, links for API documentation and tutorials

3- Playground functionality

  • “Tested examples”, i.e. ability to write code sections in the package docs that will be executed as tests during the documentation build - helps package users assess whether the documentation is up to date and makes it easier for package authors to update the docs when functionality changed
  • Ability to run code examples from packages in the playground
  • “Runnable examples” like https://go.dev/blog/examples - ability to write code sections in the docs that will (1) run as tests during the package documentation build step, and (2) render as an “inline-playground” within the surrounding documentation page

4- Other Feedback/Ideas

  • Allow URLs like [[https://ocaml.org/p/%7BPACKAGE%7D.%7BVERSION][https://ocaml.org/p/{PACKAGE}.{VERSION]]}
  • On package version dropdown - Add published date for each version
  • Security advisories / report package vulnerability
  • It would be nice to have badges for your package to display on the README so that the package repository looks attractive on the version control website where it is hosted
  • Package overview should show all the findlib library names
  • Dependencies, Reverse Dependencies and Conflicts need more space, as they can be quite narrow and tall

Vote in this topic: OCaml.org package latest version permalink URL

Archive: https://discuss.ocaml.org/t/vote-in-this-topic-ocaml-org-package-latest-version-permalink-url/11201/14

Sabine Schmaltz announced

I hereby announce that package documentation latest version permalink URLs are now live on ocaml.org. Package search results link to the latest version URL.

Our contributor Sayo has worked hard and learned a lot during the process as she tackled this project. Considering all the internal links, the canonical tag for the search engines and choosing the correct latest version by avoiding the avoid-version opam-flag made this a sizeable project!

Add to that that we kept making so many other changes all across ocaml.org’s templates that she had to git rebase through a lot of patches… I am happy to see how she has grown and that we got such a useful feature completed! :tada: :confetti_ball:

omake-0.10.6

Archive: https://sympa.inria.fr/sympa/arc/caml-list/2023-02/msg00007.html

Gerd Stolpmann announced

I just released omake-0.10.6, the build utility:

  • Support for OCaml-5
  • Fix a regression: omake can be built without ocamlopt

For docs and the download link see http://projects.camlcity.org/projects/omake.html. opam is underway.

VS Code testing extension for Alcotest and inline Alcotest PPX 0.1.0 - initial release

Archive: https://discuss.ocaml.org/t/ann-vs-code-testing-extension-for-alcotest-and-inline-alcotest-ppx-0-1-0-initial-release/11514/1

Roland Csaszar announced

I’ve just released a VS Code extension to integrate Alcotest and inline Alcotest tests with VS Code. It supports multiple workspaces/folders and uses the ’native’ Test Explorer of Code, not the Test Explorer UI extension. OCaml Alcotest Test Explorer extension GitHub repo It only discovers tests when the extension is started or a test is run, no file watching (I don’t like extensions doing this on their own). I’ll add a ’refresh’ button to the Test Explorer view, I guess, sometime. The output of Alcotest’s list of test cases is used to populate the test tree, so this is always in sync with the tests the runners ’know’ of. My compromise is the mapping of a test case to its source location, I just grep for the test case name (which can be truncated by Alcotest) in source files and pick the first match - which can be off from the ’real’ location. I personally prefer having a correct Test Explorer tree to having a correct source location. In my experience with other test extensions sometimes both the tree and the source locations are incorrect.

Some Questions:

  • Currently it only works with dune, to run the test runners and because dune files are parsed for the name of the test runners. So my question is what it would take to make it work with other build systems. Making the commands to compile and/or run a test runner and the paths to search for test runner executables configurable is easy. Making the parsing of arbitrary build files for the right targets configurable is less easy, if it is feasible at all. Of course you could always fork of the extension to exactly fit your needs
  • the extension just calls dune in the root of each workspace and it does the right thing with my projects. My question is if the right environment (sandbox) is used automatically when using the OCaml Platform extension?
  • Would add disabling the grepping for the source locations make sense for you? So you just use the (correct) test tree to start and filter tests and not waste time searching through all source files, which could take too long and doesn’t give the correct result anyway.

The extension should also be quite easy to adapt to other testing frameworks (inline test runners), as long as they support some kind of list test command line argument.

And sorry, the link to Alcotest is broken in the README, I’m going to fix this is the next release.

Roland Csaszar later added

I’ve just uploaded the version 0.2.0

Changes:

  • Drop support for VS Code versions < 1.65 (February 2022) because of Testing refresh action
  • Test discovery can be triggered by the ’Refresh’ button in the Test Explorer view
  • Bugfixes
    • Remove deleted tests from the Test Explorer tree
    • Find multiline inline test case names like `let%test\nTEST_CASE_NAME`
    • README.md: fix link to Alcotest
  • Internal Changes
    • Refactor test name parsing in source files to new function in ./src/parsing.ts and add tests

Containers is 10 years old!

Archive: https://discuss.ocaml.org/t/containers-is-10-years-old/11526/1

Simon Cruanes announced

Today marks the 10 years mark since the first commit of containers [^1] was created :tada: :partying_face:. It’s been quite a ride! I’m grateful to all users and contributors, without whom the library wouldn’t have reached its current version of 3.11 after roughly 72 releases!!

Happy birthday :camel:-:package:! :)

[^1]: containers is an extension of the stdlib, trying to complement it rather than replace it.

Outreachy Summer 2023

Archive: https://discuss.ocaml.org/t/outreachy-summer-2023/11159/5

Continuing this thread, Moazzam Moriani announced

Hi! I have joined @reynir, @pitag, @rand and Oskar to co-mentor for this Outreachy round. We have a total of three Mirage-related projects this round:

  1. Persistent Storage in MirageOS
  2. Extend the network testing tool conntest with visualizations
  3. MIDI with MirageOS

Having three projects revolve around a common theme has given us the option to be bit flexible with how we’re allocating mentor time.

I, myself, am a somewhat recent Outreachy alum. I hope to use my somewhat recent experience as an intern to try to help potential new-comers.

Old CWN

If you happen to miss a CWN, you can send me a message and I’ll mail it to you, or go take a look at the archive or the RSS feed of the archives.

If you also wish to receive it every week by mail, you may subscribe online.