-
-
Notifications
You must be signed in to change notification settings - Fork 14k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: improve fetchers overview, deduplicate readme content, follow doc conventions #297654
Conversation
cfd11e9
to
3ddf992
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
wow that's a lot of documentation!
Started reviewing in docs team meeting today. This is a rabbit hole, because there is overlapping documentation on updating FOD hashes that ended up in contributor documentation, where it arguably shouldn't be. There are also repetitions of the same mantra in various other places. Ideally we'd merge all of that in the manual's fetcher section, and link to it from everywhere else. I'll push a few commits to improve the wording on the new stuff, but recommend splitting out the reference documentation in a different PR to get some of that work merged already. |
@DMills27 and me went all the way and closed the rabbit hole. But it still needs to be split to be reviewable. |
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2024-03-28-documentation-team-meeting-notes-115/42329/1 |
1fc4499
to
5ae1b53
Compare
Co-authored-by: Dominic Mills-Howell <dominic.millz27@gmail.com>
Co-authored-by: Dominic Mills-Howell <dominic.millz27@gmail.com>
update wording in the contributors docs Co-authored-by: Dominic Mills-Howell <dominic.millz27@gmail.com>
this may be better suited for the `fetchurl` reference, but I'd prefer just rendering that information into the manual. for now, because - contributor documentation encourages mirrors - we can expect contributors to dig into the source - linking source files is trivial in in-code documentation we leave it there. Co-authored-by: Dominic Mills-Howell <dominic.millz27@gmail.com>
also improve the language a bit, and add links Co-authored-by: Dominic Mills-Howell <dominic.millz27@gmail.com>
5ae1b53
to
349353a
Compare
@fricklerhandwerk @lolbinarycat: I followed @fricklerhandwerk's suggestion and split this PR into two. Did a bit of git history rewriting to get only the relevant changes in this PR, and #300429 has the fetchurl changes. @fricklerhandwerk - I made some changes and reworded some stuff on top of your changes, please take a look at the comments from my review to understand the reasoning. Requesting your review and @lolbinarycat's and I'm hoping we can agree on a merge soon 😊 Thank you all for the reviews, I feel this has turned out much better with your involvement! |
349353a
to
1901a88
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just a few small things. The other changes are clear improvements, thanks a lot!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
look pretty good but i think there are some slight improvements that can be made.
Co-authored-by: lolbinarycat <dogedoge61+github@gmail.com> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
01a9d0b
to
defeadf
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This has probably seen enough churn now. Let's fix forward if rough edges remain.
Description of changes
This PR starts my work to update and improve the chapter on fetchers in the Nixpkgs manual. It adds more explanations on the overview of the chapter, moves content from the contributor README into the manual, and deduplicates information.
NOTE: this PR started as a change of the fetchers overview AND updating the documentation for
fetchurl
. After a lot of reviewing, we decided to split this PR into two. The PR concerns the description above. The second PR is #300429 and concerns only with updating the documentation forfetchurl
.Things done
nix.conf
? (See Nix manual)sandbox = relaxed
sandbox = true
nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"
. Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/
)Add a 👍 reaction to pull requests you find important.