Specify in which order metadata should be published to the repository #126
Conversation
joshuagl
force-pushed
the
joshuagl/issue105-metadata-write
branch
from
b2ea1ac to
4f9eca5
Compare
Adding additional worfklows to what was the "Detailed Workflows" section would insertion of an additional level of section numbering and re-numbering the existing steps in the detaile client workflow. In order to keep things simple and avoid unnecessary re-ordering of the detailed client workflow, make section 5 deal only with the detailed client worflow. Signed-off-by: Joshua Lock <[email protected]>
joshuagl
force-pushed
the
joshuagl/issue105-metadata-write
branch
from
4f9eca5 to
92f5cbc
Compare
Specify in which order metadata should be generated and made available on the repository. Fixes: theupdateframework#105 Signed-off-by: Joshua Lock <[email protected]>
joshuagl
force-pushed
the
joshuagl/issue105-metadata-write
branch
from
92f5cbc to
d2bc296
Compare
| * **3.2 Repository metadata creation** | ||
|
|
||
| Metadata SHOULD be generated in the following sequence, in order to ensure | ||
| that metadata are not referenced in the repository before they have been |
There was a problem hiding this comment.
| that metadata are not referenced in the repository before they have been | |
| that metadata files are not referenced in the repository before they have been |
There was a problem hiding this comment.
Omitting the word file does makes more sense in the context of #103. I find the plural use of metadata a bit confusing, but I think it's technically correct.
| * **3.2.2** root metadata (root.EXT) | ||
| * **3.2.3** top-level targets metadata (targets.EXT) | ||
| * **3.2.4** snapshot metadata (snapshot.EXT) | ||
| * **3.2.5** timestamp metadata (timestamp.EXT) |
There was a problem hiding this comment.
When would the mirror metadata be written?
There was a problem hiding this comment.
Oh yes, I forgot about mirror. I think it could be written at any point after the root metadata, because it's not actually referenced by or referencing any metadata explicitly.
It may make sense to list it as 3.2.6, because then we can have some confidence that an implementation conforming to the spec won't write any mirrors metadata until all of the metadata it is mirroring has been written?
There was a problem hiding this comment.
Listing it as 3.2.6 makes sense to me. We can also mention it in the paragraph above to state that it can be written at any point.
More seriously, what is the difference between "purposefully" and "purposely"? I've always used the latter. Curious... @jhdalek55 |
|
The difference between the two words is slim, yet I feel they are not interchangeable. Purposefully implies "with purpose" or something done to achieve a particular goal or aim, where as "purposely" is more a synonym for "deliberately" or intentionally. Merriam-Webster defines the difference as follows: Purposely means "on purpose" or "not by accident," while purposefully means "indicating the existence of a purpose." Although very similar, in context "purposefully" is usually used to indicate a greater level of intent or deliberate aim, as opposed to "purposely." So, in the use case above, Joshua is correct. |
😌 phew |
Update section "3.2 Repository metadata creation" to include metadata for the mirrors role. Signed-off-by: Joshua Lock <[email protected]>
| ## **5. Detailed Workflows** | ||
|
|
||
| ### **The client application** | ||
| ## **5. Detailed Client Workflow** |
There was a problem hiding this comment.
This contradicts the capitalisation change in #127
|
I have the feeling this PR tries to do multiple things at once and in such an abstract way that I am unsure if it helps the reader to better understand them. IIUC it talks about metadata interdependencies in regards to:
Moreover, I don't think that any of those requires a strict order in which the metadata is written on the repository side. For (1) and (2) the order in which the metadata is written does not really matter, as long as the interdependencies are respected. And for (3) but I think all metadata should be made available at once. My comment in #105 only had (1) in mind, and I still think that it would be extremely helpful to better understand TUF if the spec explained how metadata is updated if target files are updated/added. I just had a chat with @joshuagl and it seems like we are on the same page. He suggested that we could move targets updates, key management, and consistent snapshot all under a section that is titled something like "Repository workflows/operations". Although one can argue that any of these topics are a better fit for a secondary literature document, given that they are more concerned with operations than immediate security properties of TUF. @mnm678, @trishankatdatadog, what do you think? |
|
Converted to draft until I have made the changes discussed with @lukpueh |
|
Closing this PR because it is superseded by #153 |
Include the recommended metadata write order, as detailed in PEP 458, in a new sub-section 3.2.
This is purposefully quite a small addition, with the idea of including more detailed workflows/recommendations in the proposed secondary literature #91
Fixes #105