Skip to content
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

documentation examples #95

Open
pennywisdom opened this issue Jul 8, 2024 · 3 comments
Open

documentation examples #95

pennywisdom opened this issue Jul 8, 2024 · 3 comments
Assignees

Comments

@pennywisdom
Copy link

The following is slightly wrong:

https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L1459

Currently says "As a result of this, Alice's layout would have two steps and one inspection." but the example has 3 steps so should be "As a result of this, Alice's layout would have three steps and one inspection."

@pennywisdom
Copy link
Author

Furthermore, the explanation below this appears to be copy pasted from the first example and is missing a section:

From this layout file, we can see that Alice is expected to create a foo.py script using vi. The signed link metadata should be done with Alice's key (for simplicity, the same key is used to sign the layout and the first link metadata). After this, Bob is expected to use "tar zcvf ..." to create a tarball, and ship it to Carl. We assume that Carl’s machine already hosts an inspect_tarball.sh script, which will be used to inspect the contents of the tarball.

This needs a sentence explaining that Caroline and Alfred are expected to have run test.py.

Happy to submit a PR is that would be helpful.

@pennywisdom
Copy link
Author

pennywisdom commented Jul 8, 2024

Further down in the 3rd example (using VCS and changing to c with compilation step) the example mentions:

Carl must also make sure that the binary contained in the tarball matches the one that Eleanor reported at the end of her step

Yet the inspection in the example layout has expected materials including the source code (src/foo.c) but if this is checking the packaging step, Bob is only adding the binary to the tarball, so the example layout is confusing at it appears to be inspecting for source code that Bob isnt adding.
I would have expected the following:

"expected_products": [ ["MATCH", "foo", "WITH", "PRODUCTS", "FROM", "compilation"] ]

@pennywisdom pennywisdom changed the title documentation example slightly wrong - 5.3.2 documentation examples Jul 8, 2024
@pennywisdom
Copy link
Author

pennywisdom commented Jul 8, 2024

Should this: check-out-vcs.[UPSTREAM-DEV1-KEYID-PREFIX].link be checkout-vcs.[UPSTREAM-DEV1-KEYID-PREFIX].link?

(also https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L2020, https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L2020)

https://github.com/in-toto/specification/blob/master/in-toto-spec.md?plain=1#L1989

Also the name is corresponding to the compilation step but the link metadata name suggests vcs-check-out which is confusing.

Similarly compile-docs suggests the package step as does the verify-vsc-commits metadata link. I was expecting this to correspond to the sublayout step.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants