theupdateframework / theupdateframework/specification

Documenting fundamental concepts

Open
#109 0 comments 2 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.