Skip to content
/ rfcs Public
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

Closed
wants to merge 6 commits into from

Conversation

KFearsoff
Copy link

@KFearsoff KFearsoff commented Apr 1, 2024

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

rfcs/0174-improve-terminology.md Outdated Show resolved Hide resolved
rfcs/0174-improve-terminology.md Outdated Show resolved Hide resolved
rfcs/0174-improve-terminology.md Outdated Show resolved Hide resolved
rfcs/0174-improve-terminology.md Outdated Show resolved Hide resolved
rfcs/0174-improve-terminology.md Outdated Show resolved Hide resolved
rfcs/0174-improve-terminology.md Outdated Show resolved Hide resolved
rfcs/0174-improve-terminology.md Show resolved Hide resolved
- 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"

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

  1. https://nixos.org/manual/nix/stable/language/derivations

Copy link
Author

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.

Copy link
Contributor

@fricklerhandwerk fricklerhandwerk Apr 2, 2024

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>
@MMesch MMesch added the status: open for nominations Open for shepherding team nominations label Apr 2, 2024
@nixos-discourse
Copy link

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

@KFearsoff
Copy link
Author

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?

@infinisil
Copy link
Member

(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.
  • "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

@nixos-discourse
Copy link

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

@KFearsoff
Copy link
Author

@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.

@jtojnar
Copy link
Member

jtojnar commented Apr 4, 2024

  • 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

With all that reasoning, here are the actions proposed:

- Consider renaming IFD (Import From Derivation). Here are possible options:
- Import From Store Path (IFSP)
Copy link
Member

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.

Copy link
Author

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):

If the example you gave is indeed not IFD, we should rethink not only our term used, but also the definition.

Copy link
Member

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

@ShalokShalom
Copy link

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

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.

@KFearsoff
Copy link
Author

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.

@ShalokShalom
Copy link

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

@KFearsoff
Copy link
Author

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.

@nixos-discourse
Copy link

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

@GetPsyched
Copy link
Member

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.

@nixos-discourse
Copy link

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

@abathur
Copy link
Member

abathur commented May 25, 2024

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:

  1. Verbs encourage us to clarify who/what the actor(s) are and what they do.

  2. 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.

  3. 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?

@KFearsoff
Copy link
Author

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.

@nixos-discourse
Copy link

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

@infinisil
Copy link
Member

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.

@infinisil infinisil closed this Jun 10, 2024
@nixos-discourse
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
status: open for nominations Open for shepherding team nominations
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet