theupdateframework / theupdateframework/specification
Documenting fundamental concepts
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 405
- Forks
- 59
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 1
Description
The specification alludes to various concepts that aren't described in detail when they are mentioned. Organisationally this makes sense, to ensure the specification is tractable for implementation. However, understanding those concepts is essential for implementers and we would do well to have a canonical set of references to describe those concepts (i.e. delegation graphs, terminating flag, hashed bins and possibly more in the current spec and while adding TAP 4, with more coming down the pike in Draft TAPs).
Currently consistent snapshots has its own section in the spec, whilst other concepts are only lightly covered or not covered.
We could take one of the following approaches to better document these conceptual issues:
- TAPs: where the concept is already well described by the TAP that introduced it, link to that TAP. Otherwise create an informational TAP to describe the concept and link to that.
- Concept section/appendix in the specification: akin to the existing content on consistent snapshots.
- Combination: light summary in the specification and link to supplementary material (TAPs, papers) for more detail.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the specification's existing consistent snapshots section and the TAP 4 document linked in the issue. Catalog concepts such as delegation graphs, the terminating flag, and hashed bins, then determine which references or summaries are missing. Done means the specification has a consistent canonical reference approach for these concepts and links or explanatory material for the identified gaps.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100