rfcs
rfcs copied to clipboard
NixOS
[RFC 174] Improve Terminology
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.
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
- Doesn't need to be an RFC, can be split into component maintainers/docs team
- E.g. IFD can be decided by the Nix team (once they get to it)
- The RFC is lacking a bunch of context, e.g. "installables" doesn't necessarily even have to be a thing, it's something for the Nix team (or whoever maintains the new CLI) to decide on
- E.g. renaming "realise" to "install" is very wrong
- "packages" and "installables" also tie into Nixpkgs though, which doesn't have a dedicated team
- A lot of the terms are overloaded and used in a fuzzy manner in practice, the RFC doesn't untangle the concepts, renaming doesn't really fix the problem
- E.g. "derivation" has many meanings
- The only Nixpkgs-specific one is
stdenv.mkDerivation- This can be fairly orthogonal to Nix terms
- All of these are fairly independent issues and shouldn't have to be condensed into a single RFC
- Regarding renaming "Nix language", that's already pretty much the case and just needs more updates to manuals. Definitely not controversial.
- Just needs to be said at some point that we're going for a rename.
- Can be done without an RFC, just make a discourse post/tracking issue, ask the docs team beforehand and go for it.
- Created https://github.com/NixOS/nixpkgs/issues/301574
- "Nix DSL should be recognized as a distinct part of the NixOS Project"
- That section is a huge amount of work and not realistic right now. Some issues in the Nix repo for such work exist already.
- Renaming Nixpkgs is a huge amount of work and not worth it
- Propose to close the RFC since it's not very informed about the ecosystem and not worth the time
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:
- E.g. renaming "realise" to "install" is very wrong
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:
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
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.
- E.g. IFD can be decided by the Nix team (once they get to it)
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.
- The RFC is lacking a bunch of context, e.g. "installables" doesn't necessarily even have to be a thing, it's something for the Nix team (or whoever maintains the new CLI) to decide on
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.
- "packages" and "installables" also tie into Nixpkgs though, which doesn't have a dedicated team
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.
- All of these are fairly independent issues and shouldn't have to be condensed into a single RFC
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.
- Can be done without an RFC, just make a discourse post/tracking issue, ask the docs team beforehand and go for it.
About tracking issues - is there one for docs team across the different projects? I must have missed it, it there is.
- E.g. renaming "realise" to "install" is very wrong
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.
Well, the familiar phrases have connotations. For example, most people will probably expect that installing a package will make its programs available on PATH, which realization does not do. See also the discussion in https://discourse.nixos.org/t/do-we-have-and-use-the-right-verbs/18237/2?u=jtojnar
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.
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. They very much go against the very idea of communication.
That is why I vote for a ban of abbreviations.
Well, the familiar phrases have connotations. For example, most people will probably expect that installing a package will make its programs available on
PATH, which realization does not do. See also the discussion in https://discourse.nixos.org/t/do-we-have-and-use-the-right-verbs/18237/2?u=jtojnar
The vast majority of cases where realization happens is either installation - such as using nix profile install or nixos-rebuild switch, where the PATH is changed and realization happens implicitly, or building using nix build or nixos-rebuild build, where the PATH changes aren't implied from the wording at all.
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 venv, which isn't very different from python.withPackages - it's a nested environment with Python and Python-specific packages. I think the Python issue is more of a tooling/documentation issue, and as such it's out of scope for this discussion.
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.
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.
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.
That's the benefit of us all already speaking English.
I can totally reason, what "Import from store path" means. 'IFSP' could mean a thousand things.
International fishing society prospect 🤷🏻♂️
CS is very much a field of science. So please, let us treat it consequently.
https://www.psychologicalscience.org/observer/alienating-the-audience-how-abbreviations-hamper-scientific-communication
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: https://github.com/NixOS/foundation/issues/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:
-
Verbs encourage us to clarify who/what the actor(s) are and what they do.
-
Thinking at the intersection of verbs and actors encourages us to tease out what actors we care about, what they need to do and why (consider their motives/needs/perspectives of each), and which concepts they need to understand to achieve those needs. This in turn makes it easier to see conceptual gaps from a given perspective or when a given term depends on knowledge that isn't appropriate to drag in at that point.
-
Clarifying the actor(s) makes it easier to spot terms/definitions that describe something from ~abstract/systemic perspectives that aren't easy to understand.
(A concept explained from the perspective of nix-daemon is likely going to be hard to grok for end users who don't yet understand the daemon well enough to take and reason from its perspective. This doesn't mean it's wrong to have explanations from that perspective--just that they aren't appropriate for new end users.)
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?
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?
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