slsa-framework
Review use of terminology associated with the build word
I have re-read a bit the spec looking specially to terminology we are using. Here are my notes. English is not my native language so some of my comments may not be relevant.
- Build process: in terminology this is the definition of build
- Build: most of the time refers to the instance of a build process
- Build service: not defined. Sometime refers to build platform, sometimes to “control plane” of the build platform
- Builder: not defined. Equivalent to build tools ?
- Build system: not defined. Same as build platform ?
- Build environment: same as Build Executor (though less tainted towards an implementation from my point of view)
- Build tools: not defined. Equivalent to builder ?
- Build model: not defined but probably not needed
- Build platform: most of the time Build service is used but platform is used in terminology
- Build recipe: Equivalent to build steps ?
- Build infrastructure: Equivalent to control plane ?
- Build configuration source: Equivalent to build external parameters ?
- Build worker: Should we use Build environment ?
- Build cache: Do we need to define cache in the spec. Looks like it’s an implementation “detail”
- Builder model: Same as build model ?
- Build executor: Equivalent to build environment ?
- Build definition: this is just a build external parameter (most of time as a source of the the project to build)
- Control Plane: not defined. Probably need definition in terminology ?
From #787 by @arewm:
In #779 (comment), it was raised that both build system and build service are used without a clear distinction. This distinction should be clarified and the specification should be reviewed to ensure that the distinction is consistently used.
My comments on the distinction from the thread:
There isn't clear consistency across the requirements page. I see the build system as a generic term for the trusted boundary producing an artifact. It may be a service (GitHub Actions, etc.) or it may be a non-service (individual's machine). Since the isolation requirements for L2 are a build service, it is consistent to start talking about a build service at L2 requirements in provenance.
Here are some comments from PR 876. I move it here, because I think anyway we need to address them to add more clarity for the "Build model" section on the Terminology page. Meanwhile, I will leave the U.S. for a little while and may not be able to improve the diagram before I come back. CC @joshuagl and @lehors to ensure this is the right place to comment, in case a more appropriate issue exists.
The following came from this comment.
Diagram, text content, and aligning both are three parts. In my personal opinion:
-
A diagram could give a reader the most straightforward view without reading any text content, even if they have no technique context. Normally, a clear diagram can defeat thousands of words. When I first see the original diagram, I found:
- The diagram is too crowded: 3 different colors, more than 5 shapes with different sizes, 2 types of arrows, 3 different font sizes, text in vertical and horizontal direction, and 1 single annotation to 1 arrow dot-line. And some empty space on the right side of "interface", which looks strange. Because of these differences for each component, I cannot tell if they have different implicit meanings at first. The combination of these properties distract me from reading the following of this page, since my brain kept processing different things at that time.
- No steps exist. As I mentioned, if I have no context, I don't know which component is the start point, from left to right then top to bottom or the other way. Meanwhile, components don't always have arrows connected to each other.
- (I guess, these are the reason triggered me to make the diagram change in this PR, but please see my ask at the end.)
-
The text content is above the diagram. When reading this section the first time, I read the content, look at the diagram, then go back to try to find each diagram component in the text content (especially hard), and go back and forward several times to find the difference. However, I do think text content is more important than the diagram in the SLSA doc, since it is more precise and should have no ambiguity. The diagram may not be displayed in extreme conditions (e.g. super bad network).
- Not talking about this section, I personally prefer looking at a diagram first, then reading content to verify if the impression I got from then diagram matches what I read later, then I don't have to go back to see the diagram again.
-
Aligning both. I absolutely agree. I again personally think:
- If the content doesn't describe a component in the diagram, maybe, we should add the content for it, e.g. Build Caches.
- If the content cannot describe the step by step workflow as the diagram depicts, maybe it means either the diagram needs some improvement or the content needs to be changed to match the diagram.
The following came from another comment about using "Platform" or "Build Platform" on the Terminology page.
But, we define the term as 'platform' not 'build platform' (From Joshua)
Indeed and we can't claim that "we always use" either one because that's just not the case. We currently use a mix of these two forms through out. (From Arnaud)
It might be another improvement for the diagram: omit the word build from the components inside a build platform; Or if use platform is more desirable, every component inside the green box may have a build prefix, e.g. build environment, build cache, and build control plane.
#908 addresses most of the feedback from the comment above by @chtiangg:
Diagram:
- I reduced visual clutter by using a consistent font size for the orange boxes, replaced dash lines with solid, and used black for build caches. However, I kept "external parameters" as a separate symbol to distinguish it from the artifacts dependencies, outputs, and provenance.
- I added an arrow to connect interface to control plane. However, I didn't add numbers since I thought that added too much visual clutter.
- I removed the word "resolved" before "dependencies".
Text:
- I moved the text to be after the diagram as suggested.
- I switched to bulleted list and used more consistent language to make it easier to match between diagram and text.
I believe the only thing unaddressed is the textual description of a build cache. I wasn't sure exactly how to fit it in so I figured I'd either defer to a future PR or get input from reviewers.
I believe the term "build project" should be clarified as part of this issue as well.
It was originally called simply "project" but was later updated to be called "build project": https://github.com/slsa-framework/slsa/pull/732#discussion_r1151145101
The term is used in:
