Review (typos & minor improvements)

[alecandido]

Sorry to bother again: this time, I decided to avoid filing many more issues, and to collect feedback in a single evolving one. ~Maybe it will end up being a list of one element, but~ I want to prevent large noise generation.

Moreover, now I'd prefer reading your book cover-to-cover. When I'll approach the end, I hope I will have some time left and author a PR myself (or multiple, if needed) to fix anything that is still on this list.

Minor improvements

NixOS with flakes enabled

• [x] (Fixed by https://github.com/ryan4yin/nixos-and-flakes-book/commit/009129623484da1e7e1ae717e537404e8a25c3a4 ) I guess it's a typo, but the first occurrence of nixpkgs.pkgs should be just pkgs, isn't it? https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/nixos-with-flakes-enabled.md?plain=1#L258
• [ ] it would be nice to link an example of hardware-configuration.nix in https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/nixos-with-flakes-enabled.md?plain=1#L261 but I found no authoritative examples, and most of the people end up customizing it (so it is unreliable to link personal configs) currently, the best alternative I can propose is to link the (almost empty) nixos-generate-config wiki page
• [x] (Fixed by https://github.com/ryan4yin/nixos-and-flakes-book/commit/a15b7c738daca523873b3d4f2dcd0f19a2d6e874) _module.args is actually documented in each appendix (of NixOS, nix-darwin, and home manager), cf. https://nixos.org/manual/nixos/stable/options#opt-_module.args https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/nixos-with-flakes-enabled.md?plain=1#L278-L279 this documentation is exactly the one extracted from the description, but I would say is a better reference
• [ ] a reference to some discussion could be appreciated here: https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/nixos-with-flakes-enabled.md?plain=1#L286

Custom cache servers

• [x] (Fixed by #117 ) a lump of markup issues https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/add-custom-cache-servers.md?plain=1#L13-L17
  • the first item is marked as 2., while the second as 1. -> md takes the freedom of making them sequential, and it renders the 1. as 3. 🤦
  • the nested 1. is a list of one item - I'd suggest making it unsorted
  • (Fixed by https://github.com/ryan4yin/nixos-and-flakes-book/commit/0c21b86e9a33deb75f17fc2bb6e71d0e452f3bb5 ) How to Add ... appears like a section title, but it's a plain paragraph
• [ ] maybe it's just personal preference, but I'd make unsorted even this other nested list https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/add-custom-cache-servers.md?plain=1#L23-L24 (I usually go for numbering only when I want to reference it later, or when I want to stress the count)
• [ ] while the CA blog posts by Tweag, linked on the cited wiki page, have been an incredibly interesting reading https://github.com/ryan4yin/nixos-and-flakes-book/blob/490be22f0a3a8ba76146a891e323e63f18bf7766/docs/nixos-with-flakes/add-custom-cache-servers.md?plain=1#L52 there is not much about trust, that is instead cited here. Maybe a better reference could be https://github.com/nix-community/trustix
• [ ] trivial typo https://github.com/ryan4yin/nixos-and-flakes-book/blob/490be22f0a3a8ba76146a891e323e63f18bf7766/docs/nixos-with-flakes/add-custom-cache-servers.md?plain=1#L165 https://github.com/ryan4yin/nixos-and-flakes-book/blob/490be22f0a3a8ba76146a891e323e63f18bf7766/docs/nixos-with-flakes/add-custom-cache-servers.md?plain=1#L195-L197 I woud just replace ai with my-nixos, since more explicitn (though Ai Hoshino is great :P)

Modularize the configuration

• [ ] it is true that modules are defined in nixpkgs (as mostly the rest of NixOS), but I believe the canonical reference about modules to be in the NixOS docs (in particular the dedicated, extended, writing modules section) https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/modularize-the-configuration.md?plain=1#L27 in particular, there is an explicit section about imports (not that contains much more information, but it is definitely more friendly)
• [ ] once more: the docs are provided in the NixOS manual, ordering section https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/modularize-the-configuration.md?plain=1#L188
• [x] (Fixed by https://github.com/ryan4yin/nixos-and-flakes-book/commit/dfc73a8667d271c0d02673d26e4e918a9a93d6d1 ) broken link: https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/nixos-with-flakes/modularize-the-configuration.md?plain=1#L299

Downgrading or Upgrading Packages

• [ ] I would add a footnote (or disclaimer paragraph) about the use of import with flakes https://github.com/ryan4yin/nixos-and-flakes-book/blob/4536260f6eda6ac24272141af8f04903fe0f3d50/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md?plain=1#L39 it is true that is ubiquitous, especially for nixpkgs, but you're implicitly relying on the presence of the legacy default.nix (the flake way would be nixpkgs.legacyPackages...) it is a nice workaround even in other situations, but it's better that you know what you're doing Ah, actually there was a related not here https://github.com/ryan4yin/nixos-and-flakes-book/blob/4536260f6eda6ac24272141af8f04903fe0f3d50/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md?plain=1#L100 but I would explain that with import you're essentially taking the path, and relying on default.nix (btw, it's legacy only top-level, and perfectly fine elsewhere)
• [x] (Fixed by https://github.com/ryan4yin/nixos-and-flakes-book/commit/6d986d75c4cf066bc5e238fcfa994a56587cec72 ) Maybe use inherit? It doesn't change anything, but it is idiomatic, and I believe could be good for a beginners' book https://github.com/ryan4yin/nixos-and-flakes-book/blob/4536260f6eda6ac24272141af8f04903fe0f3d50/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md?plain=1#L42

Module System and Custom Options

• [ ] I would mention nix-darwin at the same level of NixOS and home manager https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/other-usage-of-flakes/module-system.md?plain=1#L8 and it also has its online docs (though not a search engine, to the best of my knowledge, but you can use "find in the page") https://daiderd.com/nix-darwin/manual/index.html
• [ ] while it is certainly true that modules are implemented in Nixpkgs, https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/other-usage-of-flakes/module-system.md?plain=1#L10-L16 I would still refer the reader (even in this section) to the NixOS docs first, section "Writing modules", and then also the corresponding nixpkgs "Modules system" section as a further reading (and pointing to the rendered docs)
• [ ] here there is some confusion, since the shortcut is not related to a pure declaration, but a missing one https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/other-usage-of-flakes/module-system.md?plain=1#L161 I would rephrase to make it clear that you're setting config, omitting it, since you do not need to declare any option
• [ ] here I'd avoid => config, since it never needs to evaluate the full config object, and thus config.foo is already enough https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/other-usage-of-flakes/module-system.md?plain=1#L208 I'd rephrase even the nested points, since the moment you arrive to config.foo you find out that is a leaf, and you conclude the execution, no dependency on the outer config, that's just a value (ok, it is for sure an attribute set because of lib.mkOption, but you could pretend it's the default value...)
• [ ] here, instead, I would add an initial config.warnings =>, since the starting point (CLI invocation) is always the same https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/other-usage-of-flakes/module-system.md?plain=1#L215 explaining it as a 0th point (i.e. point 1, and shift the others)
• [ ] (Related to #106 ) and here it could be worth to explain the difference between if ... then ... else and lib.mkIf in greater details, possibly going through the implementation https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/other-usage-of-flakes/module-system.md?plain=1#L223
• [ ] migrate all links to the rendered docs https://github.com/ryan4yin/nixos-and-flakes-book/blob/675409603a98cb915eb7482be62c08559b87a38a/docs/other-usage-of-flakes/module-system.md?plain=1#L357-L361

Overriding

• [ ] there is an abrupt switch from the description of .override to .overrideAttrs, without an explicit comparison (nor any introduction)
• [ ] a reference to the official docs could be valuable https://nixos.org/manual/nixpkgs/stable/#chap-overrides
• [ ] the description of nix repl usage is interspersed and redundant

Overlays

• [ ] stress that self: super: and final: prev: are equivalent, and that the latter is the "modern" terminology, while the first is still present in many places https://nixos.wiki/wiki/Overlays

Custom NIX_PATH and Flake Registry

• [ ] Not the best example https://github.com/ryan4yin/nixos-and-flakes-book/blob/490be22f0a3a8ba76146a891e323e63f18bf7766/docs/best-practices/nix-path-and-flake-registry.md?plain=1#L16-L18 since, if flakes are enabled, you can just do nix repl nixpkgs (that is a strict subset of the characters above, and makes use of flakes) but the true question is: do you really need NIX_PATH at all with flakes?

The Ingenious Uses of Multiple nixpkgs Instances

• [ ] considering this is a book about flakes, it is a bit controversial to have all these import nixpkgs around (in this and previous sections), and then cite the 1000 instances of nixpkgs
  • I don't have a clear-cut solution, but a proposal could be to turn all the import nixpkgs in inputs, possibly differently named inputs with the same URL (I have to check that this actually works, but I don't see why it should not)
• [ ] btw, better to link directly the blog post, rather than the forum post advertising it

Packaging 101

• [ ] This post by Serokell is worth a mention, given the scope of the book (flakes) and the introductory nature https://serokell.io/blog/practical-nix-flakes#packaging-existing-applications
• [ ] I would keep it simple, and provide a few opinionated examples, including
  • [ ] a straightforward example with trivial builders https://nixos.org/manual/nixpkgs/stable/#chap-trivial-builders
  • [ ] a Python example with Poetry (using poetry2nix, it can be really trivial)
  • [ ] a Rust example with Cargo (using crane, it can also be quite straightforward)
  • [ ] Serokell's Haskell is simple, but I'm not enough opinionated on Haskell to include it myself
    • it is using Cabal, but even Stack is quite popular, and I guess it be could more aligned to the flakes experience...
    • it is using cabal2nix (an official NixOS project), but haskell.nix seems to have enough momentum as well, and even better docs, supporting both Cabal and Stack...
    • I'm not enough opinionated on Haskell to suggest anything for an introduction...

Development Environments on NixOS

• [ ] it is worth mentioning direnv, since it is useful, but it could also handle automatically nix develop shell behavior https://discourse.nixos.org/t/using-nix-develop-opens-bash-instead-of-zsh/25075/6

Dev Environments

• [ ] devenv supports flakes, and it's pretty convenient (I will shamelessly link my templates)
• [ ] "Dev Environment for Python" -> I mostly write Python code (not my favorite language, but widespread enough) and devenv saved me the day (works with virtualenv and Poetry out of the box)

[ryan4yin]

Thank you very much for your review. I have just fixed some of the problems and updated them on this issue, and I will continue this work later in my free time.

[alecandido]

@ryan4yin as I wrote above, I wanted to first go through the book, to have a full overview (there are different things that you note during the first reading, or after completion - this issue is to save the first kind).

However, for the remaining ones I will contribute myself :)

This is a great collection, since Nix has valuable docs, but the information is scattered in infinite places, and there is so little for the entry level... So, I found out that I really like to contribute to the book, because then I'll be more confident to tell other people to start using Nix ("it's simple, there's a great book explaining it!").

The only piece I won't be able to contribute to for sure will be the Chinese translation, I'm sorry 😓

[ryan4yin]

I wanted to first go through the book, to have a full overview (there are different things that you note during the first reading, or after completion - this issue is to save the first kind).

Got it.

However, for the remaining ones I will contribute myself :)

This is a great collection, since Nix has valuable docs, but the information is scattered in infinite places, and there is so little for the entry level... So, I found out that I really like to contribute to the book, because then I'll be more confident to tell other people to start using Nix ("it's simple, there's a great book explaining it!").

Very much looking forward to your contribution! :heart:

The only piece I won't be able to contribute to for sure will be the Chinese translation, I'm sorry 😓

It's not a problem. I'll take care of the Chinese part.

[ryan4yin]

FYI: I have just fixed a lot of markup issues & typos via spellchecker & code formatter: #122 #123 #124 #125

[alecandido]

FYI: I have just fixed a lot of markup issues & typos via spellchecker & code formatter: #122 #123 #124 #125

That is great. For ease of writing (and referencing) I would also suggest formatting the files on 80-100 columns. I know this could be controversial, and most editors are able to wrap the lines. But, e.g., the preview of GitHub is not wrapping at all...

[ryan4yin]

I would also suggest formatting the files on 80-100 columns.

Done, Everything seems to be fine after the change. #126

[thngz]

helix example of flake and module system chapter has a small typo in the comment, you probably meant "choose" not "chose"

[ryan4yin]

you probably meant "choose" not "chose"

@thngz Fixed by https://github.com/ryan4yin/nixos-and-flakes-book/commit/dae7350debaa5baf48fcebc0d621ed93d1e3672a