Skip to content

fetchTree: add documentation#5556

Closed
kamadorueda wants to merge 1 commit intoNixOS:masterfrom
kamadorueda:issue-5463
Closed

fetchTree: add documentation#5556
kamadorueda wants to merge 1 commit intoNixOS:masterfrom
kamadorueda:issue-5463

Conversation

@kamadorueda
Copy link
Member

@kamadorueda kamadorueda commented Nov 14, 2021

  • Since this section is going to be long
    due to the need of documenting the different backends
    then giving it its own section seems reasonable.
    Additionally, by introducing fetchers before derivations and
    after the basics of the language,
    it guides the lector through the mental model
    that in Nix you build your derivations from the data you fetch
    in a reproducible way in the first place
  • Start by documenting the git backend and then I'll be adding more

Mentions #5463

- Since this section is going to be long
  due to the need of documenting the different backends
  then giving it its own section seems reasonable.
  Additionally, by introducing fetchers before derivations and
  after the basics of the language,
  it guides the lector through the mental model
  that in Nix you build your derivations from the data you fetch
  in a reproducible way in the first place
- Start by documenting the `git` backend and then I'll be adding more
@@ -0,0 +1,147 @@
**Warning**:
This section is **experimental** and its interface is subject to change.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How can this be experimental when all the old fetchers are now using this under the hood?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the warning because of this small detail:

settings.requireExperimentalFeature(Xp::Flakes);

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How can this be experimental when all the old fetchers are now using this under the hood?

I don’t think here’s a contradiction here: This is indeed used internally, but the interface isn’t stable yet. So it makes sense to mark this as experimental

@edolstra
Copy link
Member

The fetchers stuff is already mostly documented in the nix flake manpage (under "Flake references"). I think it's better to have the fetchTree doc refer to that, rather than duplicate it in another section.

@bew
Copy link
Contributor

bew commented Nov 15, 2021

The fetchers stuff is already mostly documented in the nix flake manpage (under "Flake references"). I think it's better to have the fetchTree doc refer to that, rather than duplicate it in another section.

I agree, let's not duplicate everything, but what about the other way around?
The nix flake doc page is already quite big, maybe it could refer to the Fetchers doc page for the doc of individual fetchers? (which could also document fetchTree?)

@stale
Copy link

stale bot commented Jun 12, 2022

I marked this as stale due to inactivity. → More info

@stale stale bot added the stale label Jun 12, 2022
@elikoga elikoga mentioned this pull request Jun 29, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants