[cwn] Attn: Development Editor, Latest OCaml Weekly News
Alan Schmitt
alan.schmitt at polytechnique.org
Tue Feb 28 06:38:16 PST 2023
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
Vote in this topic: OCaml.org package latest version permalink URL
omake-0.10.6
VS Code testing extension for Alcotest and inline Alcotest PPX 0.1.0 - initial release
Containers is 10 years old!
Outreachy Summer 2023
Old CWN
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
• Note: if you don’t specify an `opam' `synopsis' and/or
`description' yourself, `dune-release' derives those from your
README as described in
<https://discuss.ocaml.org/t/looking-for-ideas-for-the-package-overview-page-on-ocaml-org/11416/40>.
However, when you want to link somewhere from within the
`$(DESCRIPTION)' block, that will not work at the same time on
GitHub as well as in other documentation contexts (e.g.
locally-built offline documentation vs ocaml.org vs GitHub).
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
5- Package overview pages inspiration
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
• <https://crates.io/crates/tokio>
• <https://rubygems.org/gems/rubocop>
• <https://www.npmjs.com/package/partial.lenses?activeTab=readme>
• <https://pkg.go.dev/github.com/go-redis/redis/v8>
• <https://hex.pm/packages/phoenix>
• <https://opam.ocaml.org/packages/conduit-mirage/conduit-mirage.6.2.0/>
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:
[ocaml.org] <http://ocaml.org/>
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.
[Alcotest] <https://github.com/mirage/alcotest>
[inline Alcotest] <https://gitlab.com/gopiandcode/ppx-inline-alcotest>
[OCaml Alcotest Test Explorer extension]
<https://marketplace.visualstudio.com/items?itemName=release-candidate.vscode-ocaml-alcotest-test-adapter>
[GitHub repo]
<https://github.com/Release-Candidate/vscode-ocaml-alcotest-test-adapter>
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
[Testing refresh action]
<https://code.visualstudio.com/updates/v1_65#_testing-refresh-action-and-sorttext>
◊ 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
[./src/parsing.ts]
<https://github.com/Release-Candidate/vscode-ocaml-alcotest-test-adapter/blob/7f36d89517f6ed5b3a3fa12235bd0fd9c8571819/src/parsing.ts>
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.
[containers] <https://github.com/c-cube/ocaml-containers/>
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.
[Oskar] <https://github.com/musha68k>
[Mirage] <https://mirage.io/>
[recent]
<https://discuss.ocaml.org/t/outreachy-summer-22-closing-commemoration-session-on-23rd-sept/10450/5>
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].
[Alan Schmitt]
[send me a message] <mailto:alan.schmitt at polytechnique.org>
[the archive] <https://alan.petitepomme.net/cwn/>
[RSS feed of the archives] <https://alan.petitepomme.net/cwn/cwn.rss>
[online] <http://lists.idyll.org/listinfo/caml-news-weekly/>
[Alan Schmitt] <https://alan.petitepomme.net/>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idyll.org/pipermail/caml-news-weekly/attachments/20230228/19e2637a/attachment-0001.html>
More information about the caml-news-weekly
mailing list