-
-
Notifications
You must be signed in to change notification settings - Fork 160
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
[RFC 174] Improve Terminology #174
Conversation
rfcs/0174-improve-terminology.md
Outdated
- Rename FOD (Fixed-Output Derivation) to WKSP (Well-Known Store Path) | ||
- Converge on using "package" term for introductory materials | ||
- Converge on using "installable" term for more advanced materials. This includes cases when an installable is a runnable script, such as when building a closure of NixOS system. The term should also be used in manuals and references | ||
- Rename "derivation" to "derivation file", keeping the current definition. Define "derivation" as "an old term that is no longer used, which usually means derivation files" |
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.
But this is incorrect... That isn't the current definition. *.drv
files are store derivations, which are distinct from derivations. Derivations are specifications for "running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths."1 Notably, store derivations are a side-effect of derivations.
Footnotes
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.
Looking at the glossary definition from Nix manual for derivation, it reads as if derivation is just a structure. This is some structure that describes a build task, and Nix package managers operates with it. Crucially, the structure can be in any format at all: it can be passed from a C++ program, using the code that Nix package manager uses; it can be a JSON; it can be an aTerm; it can also be some area in RAM that holds a representation of the C++ structure in memory.
This definition isn't useful. It is essentially saying, "there's a structure that is defined in C++ code, and everything that can be serialized into it is a derivation". This is not even an implementation detail, this is more like misplaced code comment.
Notably, the definition for store derivation that you linked is much more useful. It outright states a couple of useful properties: store derivation is a derivation, it exists in store and has a store path, and it is also a .drv file. Since store derivation is actually a derivation, and it's also the predominant format of interacting with derivations even if you interface with the Nix package manager code - I'd say it makes a lot of sense to stop trying to describe what's essentially an internal structure representation, and to only describe the .drv file.
Also, that's only going by the glossary. The less thorough parts of the documentation often use "derivation" to mean "store derivation". And less formal knowledge sources pretty much always say "derivation" to mean the .drv file.
It's important to note that all of the above is not what is actually written in the text of the RFC, so that's a mistake on my part that I'll fix.
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.
A derivation indeed is just an abstract data type, the specific representation doesn't really matter. And yes, many places in the Nix manual are still sloppy on the terms.
I generally agree on the premise of this RFC, but strongly doubt it's productive to pursue: batching up terms for renaming will just delay progress on the uncontroversial ones, and clutter the discussion for the others.
Some of the terms you've listed have issues filed for finding better names (IFD). Some are arguably already solved but not used consistently yet (Nix language), some are merely not well-explained (derivation), some can be considered to be not problematic to begin with. All of that can be improved incrementally, and I'd very much appreciate your help with that.
Some terms probably aren't worth changing: Seriously trying to rename Nix is asking for trouble.
In any case I recommend to take on whatever you feel needs to be done as independent issues.
Co-authored-by: Lord-Valen <46138807+Lord-Valen@users.noreply.github.com>
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/rfcsc-meeting-2024-04-02/42643/1 |
I have pushed a commit addressing all of the feedback. Unfortunately, it seems like the diff I've made a lot of comments have "outdated" label. I tried not to touch the line that was commented, but it seems like I don't understand the mechanism that Github uses to mark things as "outdated" at all. Should I resolve the conversations, or should I leave them up? |
(discussed in today's docs team meeting) Overall we agree with the intention of the RFC, many terms could be improved and used more consistently. But we think that the RFC is not very well-informed of the current state of the ecosystem. @KFearsoff We would appreciate if you could do more research and we encourage you to get in touch with the relevant teams for getting guidance. The docs team in particular is there to help and provide pointers! We propose to close the RFC in favor of working on these issues individually. Full discussion
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2024-04-04-documentation-team-meeting-notes-117/42754/1 |
@infinisil Thank you for a very detailed response! I appreaciate the input you have for this RFC in particular, and for the community in general. That said, I somewhat disagree on the basic premise here. From my understanding, you suggest that this issue is bite-sized. Is that correct? I personally think that the issue is not in particular terms or phrases, but in how we think as a community in general. I'll provide more reason and insight further, but here's a quick example of what I value in particular:
This is very much what I want this RFC to address! My opinion is that trying to conform to the familiar words with solid intuition behind them like "build" and "install" is of extreme importance. A derivation may be "realiased" - that is, "built" manually or just downloaded from binary cache. The word "install", thankfully, covers both routes. In essence, what I want to talk about is if we want to prioritize being familiar and friendly to the users over being strict and technically correct. One isn't necessarily opposite to another: you can be friendly and correct. But currently, Nix is incrediby correct, and not very user friendly. If the RFC doesn't reflect the intention very well, please treat it as an issue with wording if the RFC. If you disagree with the premise - I urge you to treat RFC as necessary, and continue to argue in favor of that opinion. Essentially, what I'm trying to say is, we ought to simplify the model of Nix ecosystem, without losing too much of correctness. While there are many facets of that, it's a systemic issue. I want to treat it as such, so the RFC is out to formalize the issue and the details. Having an overarching issue that is being solved, but never formalized, doesn't sit right with me. Let me proceed with a number of concrete examples, if that's not enough to convince you that the issue should be formalized:
I don't claim to have the biggest knowledge of the ecosystem, I also think my opinion is still very insightful. I'm moderately involved with the community, but it seems like there's no community consensus on this matter. Hence the RFC.
Sure, it can be. But do we want to keep the "derivation" part to begin with? I feel like that's a hard prerequisite to renaming IFD to something that feels intuitive. IFD isn't technically problematic: it's an import, and that's from derivation, because a lot of stuff is a derivation already. It's not incorrect, but it's also not useful. But again - if the issue was only about IFD, then it would make sense to discuss it specifically; but the issue is if, in general, we even want to use the word "derivation" and such in general.
Sure, but once again - I want to raise a discussion if we want to empoy a project-wide sensible naming, or if we want to leave that to particular teams.
I don't think that's true, actually. Nix isn't technically tied to Nixpkgs. It's just an executor for IO functions. Still, a very large part of why Nix is useful in real world is because Nixpkgs exists. I feel like "packages" and "installables" are general and useful enough to do unification across the ecosystem.
Despite being fairly isolated from each other, I feel like the issues span across the whole community. As such - I feel like RFC is warranted, as a community-wide standard.
About tracking issues - is there one for docs team across the different projects? I must have missed it, it there is. |
Well, the familiar phrases have connotations. For example, most people will probably expect that installing a package will make its programs available on |
With all that reasoning, here are the actions proposed: | ||
|
||
- Consider renaming IFD (Import From Derivation). Here are possible options: | ||
- Import From Store Path (IFSP) |
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.
Isn't this ambiguous? import (builtins.fetchGit ...)
is also an import from a store-path, but not IFD.
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.
Are you sure it's not IFD? Our current definition for IFD suggests that it should be:
Passing an expression expr that evaluates to a store path to any built-in function which reads from the filesystem constitutes Import From Derivation (IFD):
- import expr
If the example you gave is indeed not IFD, we should rethink not only our term used, but also the definition.
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.
Minimal reproducer:
$ nix-instantiate --no-allow-import-from-derivation -E 'let git = builtins.fetchGit ./Projects/nix; in [ "${git}" (import "${git}")._type ]' --strict --eval
[ "/nix/store/xrkxv25fwqs241c5w2xvjaw7mrhs8daq-source" "flake" ]
Below ./Projects/nix
is a git checkout from Nix.
IIUC the error is indeed only thrown for drvs being in string context of an import: https://github.com/NixOS/nix/blob/12ec315/src/libexpr/primops.cc#L74-L81
Personally, I feel like abbreviations are almost always in the way. Unless everybody already knows their meaning anyway, they are building up the barrier of entry. There is no benefit in using them, they are ambiguous and carry no meaning within themselves. That is why I vote for a ban of abbreviations. |
The vast majority of cases where realization happens is either installation - such as using The discussion you linked is interesting, in particular around Python. Python doesn't actually look for libraries in PATH - it looks for them in PYTHONPATH. Python being special is especially noticeable when you bring up
I think this applies to terminology in general. Unless people are already familiar with the terms - having terms in your documentation builds up the barrier to entry. I think there's value in abbreviations - they are not significantly more confusing than regular terms, and they also allow you to formalize concepts that aren't easy to fit into a single word, but it's also true that getting rid of abbreviations is a good idea. I'll add it as a discussion point. |
That's the benefit of us all already speaking English. I can totally reason, what "Import from store path" means. International fishing society prospect 🤷🏻♂️ CS is very much a field of science. So please, let us treat it consequently. |
Apparently there's a WIP RFC about the canonical domain to be used. There's also an existing issue in the Foundation repo about naming of the project: NixOS/foundation#77 I've removed the text related to that from the RFC: makes it a lot more to-the-point. I'll likely discover more issues that are relevant to the "project naming" part (or create them myself), so this part will likely just go. Let's focus on the more technical part of our terminology being very research-like, unhelpfully formal and confusing. |
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/rfcsc-meeting-2024-04-16/43512/1 |
This RFC has not acquired enough shepherds. This typically shows lack of interest from the community. In order to progress a full shepherd team is required. Consider trying to raise interest by posting in Discourse, talking in Matrix or reaching out to people that you know. If not enough shepherds can be found in the next month we will close this RFC until we can find enough interested participants. The PR can be reopened at any time if more shepherd nominations are made. |
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/rfcsc-meeting-2024-05-14/45414/1 |
I'm not certain it's helpful here, but I opened a discourse thread 2 years go that overlaps this with a focus on verbs: Do we have (and use) the right verbs? I didn't tease it out in that thread, but this is roughly why I think verbs are important:
To be clear, I'm not saying nouns (and adjectives) aren't important or suggesting we write them out of our terminology. I just see focusing on verbs and actors as a lens that might help clarify what concepts a new end-user needs to understand in order to get their feet wet. The process of understanding those needs and finding the minimum set of concepts necessary to meet them should in turn tease out whether it makes more sense to adopt (but probably enrich) the beginner-friendly terms/concepts in explanations for increasingly-advanced audiences or just draw one or more lines in the conceptual sand and just hold back our existing thorny concepts for advanced audiences? |
You are making an unusual point, which I haven't seen worded like this before. But it is a very intriguing one. To start off with the important bit: I think your focus on verbs is 100% on point. I think you described very well what I was going for with the "top-down approach": you take the noun you care about, and you get to where you'd like to with a logical chain of actions. This makes it much easier to untangle. Another realization that I had after reading your input is less thought-out, and I need to think about it more, but I think our current documentation is very heavily adjective-based. "Derivation" is not a noun, it's an adjective: "derivation" is something that can be "realized" into the store path. This probably describes the abstractions in the codebase really well, but it's utterly useless for regular users. "Derivation" is so hard to understand because it's an adjective that pretends to be a noun; you expect it to be a noun with some meaningful definition, but it's really just an adjective that describes the trait that actual nouns can have. The word straight up just lies to you. |
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/rfcsc-meeting-2024-05-28/46113/1 |
RFCSC: This RFC is being closed due to lack interest. If enough shepherds are found this issue can be reopened. If you don't have permission to reopen please open an issue for the NixOS RFC Steering Committee linking to this PR. |
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/rfcsc-meeting-2024-06-10/46817/1 |
RFC to improve the existing naming and terminology. This in an attempt to lower the barrier to entry into Nix ecosystem by enforcing consistent and coherent naming.
Important: please don't bikeshed on the names that the RFC proposes until we've reached an agreement as to what terms should be replaced. Until there's an agreement about that - the names that the RFC proposes are only examples, and should not be treated as final.
Rendered