doc: minimal documentation of supported platforms #254741
Conversation
doc/platform-support.appendix.md
Outdated
| @@ -0,0 +1,11 @@ | |||
| # Platform Support {#appendix-platform-support} | |||
|
|
|||
| Currently, the `x86_64-linux` platform receives the highest level of support, both in terms of CI and of developer attention. | |||
There was a problem hiding this comment.
If anyone has a better, equally succint definition of the level of support here, feel free to suggest.
There was a problem hiding this comment.
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.
|
@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:
|
More like percentages of some well-defined core package sets, so that technical trade-offs about building |
The stylistic changes I don't care much about, but #254741 (comment) is more important. |
|
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
force-pushed
the
doc-support-tiers-redux
branch
from
a441a28
to
60523e1
Compare
|
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. |
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) |
@7c6f434c my concern with doing that is: I think that unless the tiers are actually implemented1 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 existing2. 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 |
@infinisil there's a link to Hydra in the previous section, and tellingly, it points to the GitHub repo. |
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. |
There was a problem hiding this comment.
@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.
asymmetric
force-pushed
the
doc-support-tiers-redux
branch
from
5aa3725
to
86b3e20
Compare
| # Platform Support {#chap-platform-support} | ||
|
|
||
| Packages receive varying degrees of support, both in terms of maintainer attention and available computation resources for continuous integration (CI). | ||
| Below is a list of well-supported supported platforms: |
There was a problem hiding this comment.
| Below is a list of well-supported supported platforms: | |
| Here is the list of platforms with some support: |
There was a problem hiding this comment.
How about these instead?
Here is the list of better supported platformsorHere is the list of the best supported platforms
asymmetric
force-pushed
the
doc-support-tiers-redux
branch
from
86b3e20
to
9822d67
Compare
|
Did you want to squash the commits yourself? Otherwise I'll just squash them when merging |
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 NixOS#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. Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
asymmetric
force-pushed
the
doc-support-tiers-redux
branch
from
efd4140
to
b19e9be
Compare
|
Yes, it was my intention to fixup before merging myself :) |
|
Backport failed for 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 |
|
Can't be backported because 23.05 still uses the XML setup for the manuals. |
|
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. |
|
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 |
|
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 |
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
sandbox = trueset innix.conf? (See Nix manual)nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)