manual: architecture overview #7066

fricklerhandwerk · 2022-09-19T20:29:45Z

this continues the effort from #6420, which originally began with #4280.

abathur · 2022-09-20T16:36:58Z

Aside: will there be a ~style guide with notes on some of the substitutions like action->task and perform->run? (Unclear from casual observation if these are just cases where you're being consistent about choosing simpler words or if this is more about using a consistent, precise vocabulary.)

fricklerhandwerk · 2022-09-20T16:59:02Z

Good question. I think this is not yet worth a firm rule. Here it's just about finding more appropriate terminology and being consistent about it.

If people find it reasonable we can just continue using it, and watching out in reviews to keep it consistent.

We discussed this up and down in the making of #6420, and I'm fairly convinced now that this is both correct and appealing to common sense. Of course still open to constructive disagreement!

abathur · 2022-09-20T17:35:55Z

Fine answers for now :)

The consistency of the edits just made me curious.

doc/manual/src/architecture/architecture.md

these changes were not merged properly and had to be reverted. see merge commit d8e54d1 for full history leading up to here.

Co-authored-by: Bryan Honof <bryan.honof@tweag.io>

this will at some point enable rendering them nicely for the web

the language has its own overview page where its properties are described in sufficient detail.

fricklerhandwerk · 2022-11-09T00:37:48Z

@edolstra please review, this is now a pure addition, and a fairly small one at that.

asymmetric · 2022-11-25T18:02:23Z

doc/manual/src/architecture/architecture.md

+Underlying the command line interface and the Nix language is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+It can also execute build plans to produce new data.
+
+A build plan is a series of *build tasks*.


I find it a bit counterintuitive that the first term introduced is "build task", only then for the term to be redefined in a "boxed paragraph".

Also, by introducing this term ("build task"), I think you're increasing the cognitive load, as it is not going to be useful in the broader Nix context.

My suggesiton is instead

Suggested change

A build plan is a series of *build tasks*.

A build plan is a series of "build tasks", which in Nix are called [derivations](../glossary#gloss-derivation).

Yes, maybe it's better to use "derivation" instead of "build task", which is not a term that appears in the Nix source.

We still don't have a definition of what exactly a derivation even is. I'd argue the term derivation should be reserved for Nix's specific implementation of build tasks, whatever it is we define it to be - store derivation or the Nix language concept.

doc/manual/src/architecture/architecture.md

SuperSandro2000 · 2022-11-25T18:40:22Z

Could we use mermaid to draw the diagrams instead of manually doing them?

fricklerhandwerk · 2022-11-25T23:28:18Z

@SuperSandro2000 I tried that first, since of course it's insane to maintain ASCII diagrams but unfortunately it doesn't work:

Mermaid doesn't offer enough control over presentation. It very quickly looks unnecessarily messy.
There is no ASCII rendering for Mermaid, which we need for terminal output (man and --help), and I can't imagine how that would be less messy if it existed.
Mermaid requires adding a huge closure the manual build to display the diagrams at all.

svgbob renders these things good enough, and allows us to have both presentations. Using it is optional since just having the ASCII is already better than no visualisation at all. We can always upgrade to a more convenient method once we find one.

@edolstra said he doesn't like the brittle custom syntax, and I concur with a smirk that

It's like markdown brought to its bitter conclusion.

I'm agnostic to the tools we use, as long as they get the job done. Right now I don't see a meaningful alternative. A few considerations:

LaTeX could work, but this is only slightly less cumbersome and needs tons of specialised knowledge to maintain.
Building something with some SVG or diagramming tool and committing both the source and the final rendering is possible in principle. But it makes the contribution process really cumbersome, due to the manual steps, requires contributors to install and learn using a very specific tool, and I know none that would give us ASCII output as well.

Do you have other suggestions?

edolstra · 2022-12-12T12:30:40Z

doc/manual/src/architecture/architecture.md

+> As far as we are concerned here, the inputs and results of a build plan are just data.
+
+Underlying the command line interface and the Nix language is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+It can also execute build plans to produce new data.


"It" here seems to refer to the Nix store, which cannot be said to execute build plans.

edolstra · 2022-12-12T12:31:34Z

doc/manual/src/architecture/architecture.md

+Underlying the command line interface and the Nix language is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+It can also execute build plans to produce new data.
+
+A build plan is a series of *build tasks*.


Yes, maybe it's better to use "derivation" instead of "build task", which is not a term that appears in the Nix source.

doc/manual/src/architecture/architecture.md

fricklerhandwerk · 2022-12-19T16:56:00Z

Discussed in depth on Nix team meeting on 2022-12-12.

Decision: fix up wording and continue async with merging

Complete discussion

@edolstra: ASCII diagrams are okay for documentation that is not user-facing
- @fricklerhandwerk: the only reason this is not in the man pages is that no one set it up yet
  - @edolstra: we probably don't want it there either
    - @fricklerhandwerk: why not? having offline documentation doesn't cost us much and can be invaluable in some situations.
- ability to render ASCII art should not be a blocker to include graphics
  - @fricklerhandwerk: agreed, but it should be kept as consideration. it would be good to include diagrams in the terminal output if we have them, and they are simple enough for it to be realistic
@Eriscon2314: summary: we want to have SVG for the HTML rendering, and edit conveniently
- @edolstra: a declarative format would be ideal, but is not a requirement. could also edit SVG in a graphical editor
  - @fricklerhandwerk: graphical editors produce very noisy output
    - @edolstra: diffability or manual editing is not required, GitHub shows SVG in previews
      - Rust Book uses plain SVG which is fairly minimal
      - @fricklerhandwerk: that's almost surely touched up by hand
@thufschmitt: PlantUML also renders ASCII https://plantuml.com/en/ascii-art
- @fricklerhandwerk: apparently only for sequence diagrams.
- @thufschmitt: also requires a huge closure
  - @fricklerhanderk: any tool that does these transformations will; choose your poison
decision: leave the ASCII for now, consider moving to SVG later
@edolstra: which level of architecture is supposed to be documented here?
- @Ericson2314: it's more user-oriented and is supposed to show behavior
- @fricklerhandwerk: will rename configuration language to evaluator
@edolstra: graph arrows and labels are not entirely clear about what they mean
- @fricklerhandwerk: the point is to have a general overview, and the subsections will go into details on each term and concept
(some more discussion over wording and intent)
decision: fix up wording and continue async with merging
assigned to @edolstra

nixos-discourse · 2022-12-19T16:59:45Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-12-12-nix-team-meeting-minutes-16/24119/1

this is to help reading the diagrams, otherwise arrows and labels were reported as being ambiguous.

nixos-discourse · 2023-01-03T12:34:14Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-01-02-nix-team-meeting-minutes-20/24403/1

nixos-discourse · 2023-04-21T11:57:35Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nix-team-report-2022-10-2023-03/27486/1

fricklerhandwerk requested a review from edolstra September 19, 2022 20:29

fricklerhandwerk added the documentation label Sep 19, 2022

bryanhonof reviewed Sep 23, 2022

View reviewed changes

doc/manual/src/architecture/architecture.md Outdated Show resolved Hide resolved

doc/manual/src/architecture/architecture.md Outdated Show resolved Hide resolved

bryanhonof approved these changes Sep 23, 2022

View reviewed changes

fricklerhandwerk mentioned this pull request Oct 5, 2022

manual: document Nix architecture #6888

Closed

fricklerhandwerk force-pushed the architecture-overview branch from e0c7f4b to 7a4edde Compare November 6, 2022 12:24

fricklerhandwerk and others added 4 commits November 9, 2022 01:29

manual: architecture overview

be8744f

these changes were not merged properly and had to be reverted. see merge commit d8e54d1 for full history leading up to here.

add articles

b5728ac

clarify subject of sentence

98447c1

Co-authored-by: Bryan Honof <bryan.honof@tweag.io>

make diagrams compatible with svgbob

3d716df

this will at some point enable rendering them nicely for the web

fricklerhandwerk force-pushed the architecture-overview branch from 7a4edde to 3d716df Compare November 9, 2022 00:29

remove external link

9d20a05

the language has its own overview page where its properties are described in sufficient detail.

thufschmitt assigned fricklerhandwerk and edolstra and unassigned fricklerhandwerk Nov 25, 2022

asymmetric reviewed Nov 25, 2022

View reviewed changes

edolstra reviewed Dec 12, 2022

View reviewed changes

suggestions from review

4ed8bb1

fricklerhandwerk force-pushed the architecture-overview branch from 62a11bf to 4ed8bb1 Compare December 12, 2022 13:29

add more explanation to diagrams

c162c90

this is to help reading the diagrams, otherwise arrows and labels were reported as being ambiguous.

fricklerhandwerk requested a review from edolstra December 20, 2022 10:32

thufschmitt merged commit a654ae8 into NixOS:master Jan 2, 2023

fricklerhandwerk deleted the architecture-overview branch January 3, 2023 12:47

fricklerhandwerk mentioned this pull request Jan 4, 2023

Render graphics in the manual #7549

Open

fricklerhandwerk mentioned this pull request Jun 12, 2023

Add description for file system objects #8500

Merged

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

manual: architecture overview #7066

manual: architecture overview #7066

fricklerhandwerk commented Sep 19, 2022

abathur commented Sep 20, 2022

fricklerhandwerk commented Sep 20, 2022

abathur commented Sep 20, 2022

fricklerhandwerk commented Nov 9, 2022

asymmetric Nov 25, 2022

edolstra Dec 12, 2022

fricklerhandwerk Dec 13, 2022

SuperSandro2000 commented Nov 25, 2022

fricklerhandwerk commented Nov 25, 2022

edolstra Dec 12, 2022

edolstra Dec 12, 2022

fricklerhandwerk commented Dec 19, 2022 •

edited

Loading

nixos-discourse commented Dec 19, 2022

nixos-discourse commented Jan 3, 2023

nixos-discourse commented Apr 21, 2023

	A build plan is a series of build tasks.
	A build plan is a series of "build tasks", which in Nix are called [derivations](../glossary#gloss-derivation).

manual: architecture overview #7066

manual: architecture overview #7066

Conversation

fricklerhandwerk commented Sep 19, 2022

abathur commented Sep 20, 2022

fricklerhandwerk commented Sep 20, 2022

abathur commented Sep 20, 2022

fricklerhandwerk commented Nov 9, 2022

asymmetric Nov 25, 2022

Choose a reason for hiding this comment

edolstra Dec 12, 2022

Choose a reason for hiding this comment

fricklerhandwerk Dec 13, 2022

Choose a reason for hiding this comment

SuperSandro2000 commented Nov 25, 2022

fricklerhandwerk commented Nov 25, 2022

edolstra Dec 12, 2022

Choose a reason for hiding this comment

edolstra Dec 12, 2022

Choose a reason for hiding this comment

fricklerhandwerk commented Dec 19, 2022 • edited Loading

nixos-discourse commented Dec 19, 2022

nixos-discourse commented Jan 3, 2023

nixos-discourse commented Apr 21, 2023

fricklerhandwerk commented Dec 19, 2022 •

edited

Loading