doc: minimal documentation of supported platforms

[asymmetric]

This commit adds minimal documentation of the supported platforms.

More exhaustive documentation would require producing a list of platforms for each of the 7 tiers. This was attempted in #245368, but it quickly became clear that that would be a long-term effort.

In the meantime, this commit adds the most important information to the manual.

Description of changes

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 23.11 Release Notes (or backporting 23.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

[asymmetric]

If anyone has a better, equally succint definition of the level of support here, feel free to suggest.

[asymmetric]

CC'ing @7c6f434c and @amjoseph-nixpkgs as participants in #245368

[henrik-ch]

lgtm

[06kellyjac]

LGTM

Might be worth getting an updated platform list at some point

[infinisil]

I feel like this is missing a link to Hydra, but it's also really difficult to establish a good such link, because the nixpkgs Hydra project is not great to look at. Ideally we'd be able to express platform support as a percentage of packages that build successfully. But that's for the future.

[asymmetric]

@infinisil How strongly do you feel about your requests for changes? As it is, they are all part of a blocking review. For stylistic issues, it would be great if we could either:

• Leave it up to the author
• Justify with some consensus (ideally written down)
• Make it clear that they are "nits"/personal opinion

[7c6f434c]

Ideally we'd be able to express platform support as a percentage of packages that build successfully.

More like percentages of some well-defined core package sets, so that technical trade-offs about building python3*Packages don't change the stats when not warranted.

[infinisil]

@infinisil How strongly do you feel about your requests for changes? As it is, they are all part of a blocking review.

The stylistic changes I don't care much about, but #254741 (comment) is more important.

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-09-14-documentation-team-meeting-notes-80/33033/1

[asymmetric]

Please review again. I've moved the chapter way up in the manual (in the position we discussed in the meeting).

I've decided not to add an appendix with an outdated platform list -- this will have to be done in a follow up PR, if someone has the resources to produce an up to date one.

[pennae]

@pennae the consensus is that it should be prominent, so not an appendix. If I made it an inline content of Using Nixpkgs, could I give it an anchor?

you can, but that would mean dropping the heading. if immediate prominence is the goal then sure, make it a chapter so it'll stand out—there's no reason we can't revise the structure later if a better place becomes evident. (personally we'd add that chapter at the end of the part and, as time comes, put porting/cross-compiling/etc information there)

[asymmetric]

But at least the definitions of the tiers could be copied to an appendix?

@7c6f434c my concern with doing that is: I think that unless the tiers are actually implemented¹ in practice, there is little point in adding them to the manual, and could even be misleading.

It seems to me that there's at least some (and maybe a lot of) work that would need to be done "behind the scenes" before the tiers can be said to represent something actually existing². At that point the definitions should definitely be added to the manual.

But that's work I realized I wasn't able to do (see #245368), so I'd prefer to keep these two aspects separated.

Footnotes

1. By implemented I mean: followed by platform maintainers, reflected in organizational structure, CI ↩

2. It could also be that I'm wrong, and that the tiers are mostly implemented, which goes to show I'm not the right person to make the call of whether this should be included. ↩

[asymmetric]

I feel like this is missing a link to Hydra, but it's also really difficult to establish a good such link, because the nixpkgs Hydra project is not great to look at.

@infinisil there's a link to Hydra in the previous section, and tellingly, it points to the GitHub repo.

[7c6f434c]

By implemented I mean: followed by platform maintainers, reflected in organizational structure, CI.

It kind of has nothing to reflect in CI, it works the other way round, no? At the end of the day, tiers are rules of arbitration of tradeoffs when platform maintainers and package maintainers have different interests. The rules take into account the CI situation.

[fricklerhandwerk]

@henrik-ch and me checked what it looks like, and we think it's fine having it as a top-level chapter. Some small wording suggestions, otherwise good to merge.

Concerns have been addressed.

[infinisil]

Otherwise this looks good!

[infinisil]

Suggested change

	Below is a list of well-supported supported platforms:
	Here is the list of platforms with some support:

[asymmetric]

How about these instead?

• Here is the list of better supported platforms or
• Here is the list of the best supported platforms

[infinisil]

Either sounds good!

[infinisil]

Did you want to squash the commits yourself? Otherwise I'll just squash them when merging

[asymmetric]

Yes, it was my intention to fixup before merging myself :)

[github-actions]

Backport failed for release-23.05, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally.

git fetch origin release-23.05
git worktree add -d .worktree/backport-254741-to-release-23.05 origin/release-23.05
cd .worktree/backport-254741-to-release-23.05
git checkout -b backport-254741-to-release-23.05
ancref=$(git merge-base 85ff1d16872969aef314e2577e2d0cfcf9b42114 b19e9bebdc8ee7dce5a4c40e510165f0011008b7)
git cherry-pick -x $ancref..b19e9bebdc8ee7dce5a4c40e510165f0011008b7

[asymmetric]

Can't be backported because 23.05 still uses the XML setup for the manuals.

[infinisil]

As also mentioned on Matrix, a manual backport would still be doable, however it's not very easy and this doesn't seem worth it, so not crucial.

[nixos-discourse]

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

https://discourse.nixos.org/t/this-month-in-nix-docs-5-september-2023/33856/3

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-10-05-documentation-team-meeting-notes-84/33877/1