nix-community/srvos

Document use of `_file`

soupglasses opened this issue · 2 comments

soupglasses commented

Is your feature request related to a problem? Please describe.

In commit 43d2842 all nix files were chosen to be self-referenced using _file attribute to be better supported by nix flake check.

Describe the solution you'd like

I think it would be important to document why this choice was made for newcomers, for example a note of its use in README.md, and importantly, any possible open issues that track this issue upstream.

Describe alternatives you've considered

Not documenting its usage, risking teams not applying this pattern correctly, or even wanting it removed because they do not see its value for being there.

Additional context

When reading over the source code, especially if you are new to nix, the use of _file = file.nix may seem very counter intuitive and strange to read. Since surely nix knows where its own files are, right?

Mic92 commented

Sounds like a good idea. @zimbatm do you have a good template for a contributing guide to add this one too?

zimbatm commented

It took me a minute to put the docs infrastructure in place. @imsofi do you mind looking at the PR and tell me if that's what you had in mind?