Skip to content

Add glossary of terms to the docs - #136

Merged
ascerra merged 1 commit into
mainfrom
ascerra/add-glossary-122
Apr 3, 2026
Merged

ascerra merged 1 commit into
mainfrom
ascerra/add-glossary-122

Conversation

@ascerra

@ascerra ascerra commented Apr 1, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds docs/glossary.md — a shared vocabulary reference for the fullsend project — and links it from README.md.

Closes #122

What's in the glossary

30 terms organized alphabetically, each with a 1–3 sentence definition and links to the relevant problem doc, ADR, or issue for deeper context. Terms were sourced from:

High-friction terms given extra attention

Term Why it needed a glossary entry
Trust Overloaded across identity/content/execution contexts — broke into three sub-definitions
Zero Trust Frequently misunderstood as "accept nothing" rather than "verify everything"
Entry Point Previously "wrapper" — rename caused cross-issue confusion (#101)
Sandbox Overloaded between security primitive and general execution environment
Triage Scope (routing vs. fixing vs. reproducibility) has been a recurring discussion
Harness Industry-new term (Feb 2026), not self-explanatory

Terms added beyond the original issue list

Based on meeting notes and issue discussions, the glossary also covers: Automerge, Draft Mode, Evergreen, Identity, Label State Machine, MCP Server, Observability, Policy Store, Rework Rate, Sidecar, Slash Command, Work Coordinator, and several architecture.md components that needed definitions accessible outside the architecture doc.

Approach

  • Alphabetical organization with H2 letter headers for scannability
  • Each term links to the authoritative source doc
  • Cross-references between related terms (e.g., Flapping → Escalation, Skill → Harness)
  • Intro text encourages PRs that introduce new terms to update the glossary

Future work (not in this PR)

Per @maruiz93's suggestion on #122, a CI check that validates glossary terms are linked throughout the markdown docs would be a good follow-up.

Made with Cursor

@ascerra
ascerra marked this pull request as draft April 1, 2026 18:48
@ascerra
ascerra force-pushed the ascerra/add-glossary-122 branch 2 times, most recently from 466f7e4 to 5fa4465 Compare April 1, 2026 19:20
@ascerra
ascerra marked this pull request as ready for review April 1, 2026 19:21
@ascerra

ascerra commented Apr 1, 2026

Copy link
Copy Markdown
Contributor Author

@maruiz93 or anyone else reviewing I'm wondering if I should have cursor go through all files and link instances of these terms back to the section that they are defined in this glossary.

@ascerra
ascerra requested a review from maruiz93 April 1, 2026 19:27
@ascerra
ascerra marked this pull request as draft April 2, 2026 14:23
@ascerra

ascerra commented Apr 2, 2026

Copy link
Copy Markdown
Contributor Author

Updating this PR based on todays meeting notes

Closes #122

Made-with: Cursor
Signed-off-by: Adam Scerra <ascerra@redhat.com>
Made-with: Cursor
Assisted-by: cursor
@ascerra
ascerra force-pushed the ascerra/add-glossary-122 branch from 5fa4465 to 21d83f0 Compare April 2, 2026 14:28
@ascerra
ascerra marked this pull request as ready for review April 2, 2026 14:29
@ascerra
ascerra added this pull request to the merge queue Apr 3, 2026
Merged via the queue into main with commit d6ab6b3 Apr 3, 2026
1 check passed
@ben-alkov
ben-alkov deleted the ascerra/add-glossary-122 branch April 23, 2026 16:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a glossary of terms to the docs

2 participants