doc: add styleguide on use of with to CONTRIBUTING.md

[lolbinarycat]

Closes #292468

---

Add a 👍 reaction to pull requests you find important.

[eclairevoyant]

I think as-is, this is too narrow of a scope (focusing on meta only). Perhaps this should be phrased to discourage with in any scope where its use may cause confusion. Clarifying the use in meta within a couple of bullets is fine to me, as long as we also explain (and focus on) the general policy.

[eclairevoyant]

perhaps link to the nix.dev documentation here?

[lolbinarycat]

i considered it, but honestly, i don't think very highly of that guide, as it frankly lacks a lot of nuance, and feels like it might as well call with a deprecated feature. it doesn't provide any examples of times it would be ok or even encouraged to use.

[eclairevoyant]

That guide can be improved too: https://github.com/NixOS/nix.dev

[infinisil]

I think it would be great to improve the article on with with acceptable uses and a better explanation of the problems. We can also link it from here for completeness already though.

I think this contributing section here is still valuable since it's more Nixpkgs specific and doesn't necessarily apply to Nix in general.

[AndersonTorres]

Voicing my opinion as a with-hater, I am against merging this pull request.
The merits of getting rid of with are mostly technical, not stylistic.

If the technical merits of banishing with to the most limited scopes (namely, a single line) don't convince everyone, then it is not good to force it over everyone - and way worse is to force it as a style.

[lolbinarycat]

@AndersonTorres this PR does not "banish" the use of with at all. instead it only restricts its usage in specific scenarios that are widely considered confusing and hard to read.

for example, nested with makes it hard to tell where an identifier is coming from.

[infinisil]

Discussed in the docs team meeting today.

I don't have much of an opinion here, I'm also not a fan of with, and don't think it would be problematic to have it in the style guide, but I can also understand @AndersonTorres' arguments.

[infinisil]

I think it would be great to improve the article on with with acceptable uses and a better explanation of the problems. We can also link it from here for completeness already though.

I think this contributing section here is still valuable since it's more Nixpkgs specific and doesn't necessarily apply to Nix in general.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-03-14-documentation-team-meeting-notes-113/41462/1