JSON array auto-indenting tool: Language

[petertseng]

Summary

In this discussion, I am thinking about what language I (or an interested contributor in my stead) would use to write the JSON array auto-indenting tool mentioned as a potential follow-up step in #1917 (comment). The primary criterion I am considering is the level of burden it would present to contributors.

Motivation

In #1917, JSON files were auto-formatted and CI was made to check that they remain formatted... but 33 out of our 118 JSON files had to be excluded, because prettier formatted the arrays in a way that we decided was unsuitable. For example, for connect and go-counting it would put the lines of some boards all on one line, which harms their readability. However, excluding those files means they could potentially become badly formatted at some unknown point in the future.

(This would be a good moment to pause and reflect on whether this discussion is worth pursuing at all. Why does it matter if our files become badly formatted? If it doesn't matter, it'd be wiser to spend our limited time on other more important matters)

To allow CI to be able to automatically format those files but still keep them readable, I put forward the idea of writing some tool that could be run after prettier is run and whose only job is to reformat arrays according to our liking.

(This would also be a good moment to pause and reflect on whether there are other ways to achieve the goal of keeping our files formatted. We shouldn't tunnel-vision on just one solution without having convinced ourselves we've sufficiently explored the solution space)

Criteria

The main thing I'm considering is the experience of a contributor. Someone wants to make a contribution, but their contribution doesn't meet one of our CI checks for some reason. How easy it for them to remedy their problem?

The CI checks are in various languages:

• Python (check-immutability.py)
• JavaScript (package.json which tests the schema and the formatting)
• Ruby if Reorder keys #1960 is merged (JSON keys ordering)
• Unix shell check_required_files_present

So far, it's sort of okay if a contributor installs none of these languages, because for all of these checks the CI output can tell them what they did wrong. They would be slightly disadvantaged in not having a tight feedback loop if they weren't able to run the relevant CI check locally, but there would at least be a feedback loop available to them.

I think the formatting one is the most critical here. For the other CI checks (immutability, schema, key ordering, required files), it's mostly self-explanatory what you have to do to fix it, and the needed changes can be done by hand. But for matters of formatting, the most expedient way to fix that is to run the formatter, and if they can't, they're out of luck. It is likely for this reason that the GitHub Action to format the code was created in #1941. That made it so that if you can't run the formatter locally, you can rely on the GitHub Action to do it.

Because of the formatting CI check being critical in this way, I'm wondering whether it'd be a bad idea to write such a tool in Ruby, the most likely language I would use to write it if no other overriding reasons presented themselves. Then a contributor would have to install Ruby in addition to Prettier in order to be able to format locally. There still is the GitHub Action available, and I don't know how likely it is to actually be a problem. I also considered doing it in just Unix shell + sed, but my skill with sed was not quite enough to make it work, and I also don't know if I would be presenting a burden to Windows users. I guess there is the option of JavaScript since prettier is written in that, but I am currently not set up to be able to run JavaScript locally (neither Node nor NPM nor Yarn installed).

I don't know if I'm just imagining problems that won't ever materialize (contributors complaining that they can't run the formatter locally because they don't want to install two different things to be able to do it). Maybe the way forward is just to write something and see what happens. If later on we discover it's better to have it in a different language, then we could consider rewriting it then. I would try to make the tool as simple as possible to make it easy to rewrite.

[ErikSchierboom]

Because of the formatting CI check being critical in this way, I'm wondering whether it'd be a bad idea to write such a tool in Ruby, the most likely language I would use to write it if no other overriding reasons presented themselves.

I would personally be fine with the tooling being in Ruby and it being part of CI and the /format workflow.

I don't know if I'm just imagining problems that won't ever materialize (contributors complaining that they can't run the formatter locally because they don't want to install two different things to be able to do it). Maybe the way forward is just to write something and see what happens. If later on we discover it's better to have it in a different language, then we could consider rewriting it then. I would try to make the tool as simple as possible to make it easy to rewrite.

Personally, I would "just" build the tool and see how often it becomes a problem.