[opam-devel] [ANN] opam-fmt 1.0

[Gabriel Scherer]

Hi opam-devel,

As part of the discussion in

  bulk addition of 'ocamlbuild {build}' dependencies
  https://github.com/ocaml/opam-repository/pull/5140

it became apparent that performing bulk updates on opam-repository is
made harder by the fact that the parse-print roundtrip does not
preserve human-formatted opam files. For my proposed patch I tried to
separate the reformatting of opam file (to follow the opam-lib printer
convention) from the actual changes in two separate commits, but that
means more work for script authors, and also creates patches that are
harder to review. (If (re)formatting was controlled by the maintainer
of the OPAM packages instead of authors of bulk updates, we would be
more confident in its correctness.)

In order to move that discussion forward (how to maintain opam
metadata in a way that is easy for both human and scripts to work
with?), I propose the opam-fmt script that can be found at
  https://github.com/gasche/opam-fmt/

I wrote it in the last few days and there are probably some rough
edges. Once I feel that it should work, I may try to package it on the
opam-repo (in the meantime, clone then pin).

This suggests one possible way forward: publicize opam-fmt, encourage
users to reformat their opam files using it, adapt the opam-repository
QA to call `opam fmt --check` on opam files proposed in PR to enforce
it, and after some time (once we trust it works as expected thanks to
the human guinea pigs) reformat all older opam files to get a perfect
round-trip on all files of the repository.
It is not clear to me that this is the best way forward. (For example
it means that, in the current state of the opam file parsing/printing
code, comments in opam files would always be erased by reformatting.
Should we remove comments from the valid syntax of opam files, or
attach them to configuration lines to re-print them correctly later,
or maybe refuse to work on files with comments?) Opam developers and
repository maintainers may decide that the cost of caring about
reformatting outweigh the benefits in terms of scriptability.

What do you think?