Enable formatting projects without an .ocamlformat by default

[tmattio]

This is a follow-up on ocaml/dune#5768 to continue the discussion on whether ocamlformat should support formatting projects without an .ocamlformat configuration file by default.

@gpetiot mentioned in the PR above that he thinks the current behavior should be preserved.
I still wanted to provide a few arguments in favor of supporting the formatting of projects without an .ocamlformat file here nonetheless.

One pain point that is not specific to ocamlformat that I'm hoping to alleviate with this is the number of configuration files needed to have a full development environment.

By full development environment, I mean a project where I can execute common developer workflow easily (e.g. formatting the code base).

Not requiring a configuration file for ocamlformat would remove one of these.

My understanding of why we want to enforce a configuration file is to prevent different people from formatting the code with a different version of ocamlformat. I see a few problems with enforcing the configuration file to work around that:

• The version field is not required in .ocamlformat. We can see a lot of .ocamlformat files in the wild that don't have this field. And so just requiring an .ocamlformat file does not solve the above problem.
• The above is only a problem when multiple people work on the project. It's not the case for a lot of projects, and in particular for a beginner that is working on a hello world project.

And to go further, I think removing the need for an .ocamlformat file would improve a few scenarios:

• A new user who generates a project with dune init a the moment won't be able to format their code. They would have to search which formatter to use, and how to enable it. We can hope that they will stumble upon the dune formatting documentation or the best practices on ocaml.org quickly, but this will still remain a friction point for beginners.
• ocamlformat, even if it provides a great degree of flexibility when it comes to the formatting configuration, doesn't encourage users to configure it. Not requiring an .ocamlformat file would be a good way to incentivize people to use the default profile.

Let me know what you think 🙂

[gpetiot]

I am still not sure this is the best, but what we could do is to also enable for the formatting if we are in one of these cases, the dune-project file must define one of these:

• (using fmt 1.x) < dune 2.0
• (using fmt 1.x (enabled_for ocaml [...])) < dune 2.0
• (formatting (enabled_for ocaml [...])) > dune 2.0
• not (formatting disabled) > dune 2.0

This way we still have the constraint "we detect we are in a dune project" checked, we just enable it by relying on an explicit stanza in the dune-project file instead of an .ocamlformat file (that could be potentially empty).

cc @Julow @jberdine @emillon

[mimoo]

I would instead suggest an opt-out instead of an opt-in. If you REALLY don't want to use formatting in your project (which is a bad idea already), then create an ocaml-format.json config file (currently doesn't have an extension, but that's another issue :D) and disable it there

[grayswandyr]

Asking for an .ocamlformat file (even empty) is yet another burden for newcomers (I teach OCaml to postgraduates every year). I think formatting should indeed work by default but it would perhaps be useful to also consider that not all users will want to use ocamlformat as a formatting tool (there may be, actually there are, alternative tools). So a plain opt-out option is perhaps a bit crude, compared to the possibility to tell which formatting tool you want (or none). So you could perhaps activate ocamlformat if not (formatting X) > dune 2.0, where X is either disabled or the name of a tool (even if for now we don't have such tools plugged in dune).

[mimoo]

having several formatter competing in a language ecosystem is really not a great situation IMO. I was imagining that if you work on a project that really doesn't want to use ocamlformat, then you'd create an .ocamlformat file locally (containing something like format=no) listed in your .gitignore so that your own local ocamlformat doesn't touch anything

[grayswandyr]

having several formatter competing in a language ecosystem is really not a great situation IMO

In a given project, I agree, but in a language tooling, I don't see why. In any case, I don't see why dune should enforce a single solution if it's not too much work to pave the way for alternative formatters.

you'd create an .ocamlformat file locally (containing something like format=no)

I think using a directive in the dune-project file is better than asking people to add a file specific to a given tool, precisely not to use the said tool. What's more, my suggestion (a refinement of @gpetiot 's) is more general, for a development effort that doesn't seem too high compared to others (but I'm not a dune developer).

[tmattio]

Thanks for starting the discussion and sharing your feedback @mimoo and @grayswandyr!

To answer

having several formatter competing in a language ecosystem is really not a great situation IMO

and

I don't see why dune should enforce a single solution if it's not too much work to pave the way for alternative formatters.

This is exactly why we have the OCaml Platform. If a new formatter enters the playing ground tomorrow, it can be incubated in the Platform. No two tools that solve the same problem can exist in the Active stage of the Platform, so if the user base of this hypothetical formatter grows to the point the formatter should be in the Active stage of the Platform, we'll have to think of how to resolve this to avoid splitting the ecosystem: either by merging the tools, or by moving ocamlformat to Sustain and offer a transition path to that new formatter. FTR this is exactly the situation dune-release and opam-publish are in: dune-release is used by many users, but to move dune-release to Active, we need to figure out a way to not have two competing tools to publish opam packages.

This doesn't mean that the two formatters can't be integrated in Dune at the same time, but an integration of a Incubated tool would probably be opt-in and experimental (like the integration of Mdx in Dune at the moment, which requires a (using mdx 0.3))

[grayswandyr]

@tmattio ok, thanks. But what is the OCaml Platform's position w.r.t. not asking users to create yet another file (an empty .ocamlformat) to get ocamlformat to work out of the box?

[tmattio]

But what is the OCaml Platform's position w.r.t. not asking users to create yet another file (an empty .ocamlformat) to get ocamlformat to work out of the box?

Some guiding principles to improve the user experience include having good defaults, or strong backward compatibility. In that sense I think the proposal makes sense, however, these are guiding principles that should inform the target user experience, the goal isn't to impose technical decisions on the maintainers, so it's up to the OCamlFormat maintainers to see what they want to do with this proposal. These decisions take into account user feedback, the principles of the Platform, but also the existing technical constraints: it's quite possible that introducing this change makes sense in the future but not immediately for instance.

[Julow]

I believe the reason for OCamlformat to refuse to format in some cases is to support "formatting on save" in editors.

Formatting on save a file that shouldn't be is potentially more annoying than OCamlformat refusing to work for obscure reasons.

The current behavior is surprising and reading the dune-project file makes the situation more complex. I would like to use OCamlformat when I don't have Dune setup yet.
I suggest a breaking-change approach that separate the "formatting on save" workflow from the default behavior:

• OCamlformat formats by default. It does not try to guess whether it should format or not unless told otherwise.
  Basically as if the option --enable-outside-detected-project was on by default.

• A new flag, eg. ocamlformat --on-save, that makes OCamlformat not format if no .ocamlformat file could be found.
  Basically the current behavior. Editors implementing formatting on save would use this new flag.

This changes the default behavior and is dangerous for users of the previous behavior, which are believe are common.