Formatting rules for Nixpkgs


#1

Hi,

I propose we start forming some formatting rules for in Nixpkgs, and my main motivation for this is to minimize merge conflicts. Therefore, I propose a formatting style that minimizes those (or at least keeps it easier to read), which essentially means every item/attribute should be on it’s own line. Ideally we would have a formatter (https://github.com/NixOS/nix/issues/832) as well, but that can come later.


#2

Actually I disagree here. I think a style guide without tooling in practice is almost meaningless, except for adding minor annoyance to a random subset of people opening PRs, without any real benefits. Give me nixfmt, especially nixfmt that ofborg can use to mark misstyled PRs as broken, and then I’m 100% on board.


#3

I agree with @shlevy. Have a tool provide most of the styling for you. If the tool cannot provide all the style you want, a small number of conventions for Nixpkgs on top of that can work (over time nixfmt can adopt those, this allows nixfmt to be feature incomplete for initial adoption), but at the moment a style guide with no tooling is too large an obstacle.


#4

This is not a case of chicken and egg. A style guide is required to then write tooling to enforce it.

I have often seen questions similar to “where’s the style guide?” and this is always met with “there is none”. And for as long as there is no style guide, no one can follow it. When a style guide will be written up, people can start following it. Even without enforcement, this can decrease the burden of maintainership by at least having prescribed rules to follow. While not every contributors will, at least part of the core, if not all maintainers, might coalesce to a more unified style through the style guide.

I am, though, completely in agreement that enforcing the style guide without tooling is not feasible.

Lastly, it’s often been pointed out that we need nixfmt, but as it’s not been written yet, there must be reasons. Why should we stop an improvement effort because it’s not perfect? Unless you’re writing said tooling, halting efforts in their tracks is counter-productive IMO. The current status quo (no style guide, no tooling) is markedly worse than the suggestion (style guide, tooling later).


#5

I have been writing tooling for this, though the project has for the
time being been halted due to hnix's current lack of comment
annotations.

As a consequence, I want to say: by all means, let’s get a style guide
through as soon as possible (but let’s not refuse or slow down any
contribution that doesn’t respect it so long as we don’t have tooling
for it).

Such a style guide would help writing the tooling, and would eg. allow
me to know whether my a-bit-extreme approach (completely parse then
rebuild the file from the annotated AST) is actually something that
might work according to the style guide or not.

The more precise the style guide, the better for formatter writers.


#6

@Ekleog I’ve got some Haskell experience, what do you need? How can I help?


#7

@tomberek Currently I’m blocked on [1] being solved, so that I’ve got a
way of not losing comments in the process of formatting the code.

BTW, in [1] there are also comments from other people doing formatters
using hnix.

If you can do [1] I hope I could handle completing my current draft of a
formatter [2] that currently unfortunately drops comments.

[1] https://github.com/haskell-nix/hnix/issues/57

[2] https://github.com/Ekleog/nix-bikeshed/