Skip to content

Audit assignment vocabulary in prose and code symbols - #142

Open
scott-rc wants to merge 3 commits into
sc/assignment-redesign-4from
sc/assignment-redesign-5
Open

scott-rc wants to merge 3 commits into
sc/assignment-redesign-4from
sc/assignment-redesign-5

Conversation

@scott-rc

@scott-rc scott-rc commented May 11, 2026

Copy link
Copy Markdown
Contributor

Phase 5 of the assignment-redesign plan. Phases 1-4 changed the canonical surfaces (Go types, gRPC fields, HTTP headers, K8s annotations, Prometheus labels, OTLP attributes, slog keys, CLI flags, Web UI routes) but the long-tail surfaces lagged behind. This sweep brings them in line: doc-comments across internal/, README.md, the architecture and guide pages, help-text description: tags, one Prometheus Help: string, the assignmentHashIndex const value ("functionHash" -> "assignmentHash"), a handful of stale Test*/Benchmark* identifiers, and the previously-untracked UBIQUITOUS_LANGUAGE.md at the repo root.

A new forbidden-tokens doclint rule (with a TDD-style test in internal/dev/doclint/forbidden_tokens_test.go) catches regressions for FunctionHash, FunctionFromHeader, skipper.Function, skipper.FunctionKey, and functionHash -- five symbol-shaped tokens that have no legitimate post-rename usage. The test also pins the word-boundary edge case so skipper.FunctionKey does not double-match the bare skipper.Function pattern.

fn -- the short form of "function" from before this domain became "assignment" -- is renamed across the Go codebase to Assignment-based names. Parameters and locals use short a to match existing func (a *Assignment) ... receivers; struct fields and compound identifiers use the full word (assignment, assignmentHeader, assignmentFilter, defaultAssignment, etc.). Genuine func-value callbacks in timer.Poll/Loop and the doclint forEach* helpers keep fn, since there it names a function value rather than an Assignment.

docs/content/guides/deploying-functions.md is renamed to deployments.md (and the docs sidebar in cmd/dev/docs.go updated to match), since the page is really about labelling K8s deployments for Skipper to pool -- a more accurate framing than either "Functions" or "Assignments".

Stacked on top of #141 (Phase 4: flat policy surface + 9 wired knobs). Plan: tmp/assignment-redesign/plan.md.

Phases 1-4 changed Go types, gRPC fields, headers, annotations, metric
labels, OTLP attrs, slog keys, CLI flags, and Web UI routes. This sweep
brings the prose surfaces in line: doc-comments, README examples, the
architecture and guide pages, help-text descriptions, one Help: metric
string, the assignmentHashIndex const value, several stale Test/Bench
names, and the previously-untracked UBIQUITOUS_LANGUAGE.md at the repo
root. A new doclint forbidden-tokens rule (with a TDD-style test)
catches regressions for FunctionHash, FunctionFromHeader,
skipper.Function, skipper.FunctionKey, and functionHash.

docs/content/guides/deploying-functions.md is renamed to
deployments.md, since the page is really about labelling K8s
deployments for Skipper to pool.
@scott-rc

scott-rc commented May 11, 2026

Copy link
Copy Markdown
Contributor Author

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit afd8290. Configure here.

Comment thread internal/skipper/assignment_keys_test.go Outdated
scott-rc added 2 commits May 11, 2026 17:42
The previous rename pointed TestAssignmentKeyEquivalence,
TestAssignmentKeyConcurrent, and BenchmarkAssignmentKeyAttr at
AssignmentKey only and dropped coverage of LegacyFunctionKey, even
though LegacyFunctionKey is still actively used on every dual-emit
production path (controller server, supervisor converge, router
telemetry). A caching regression on LegacyFunctionKey would have gone
undetected. Parametrise each test over both cached *Assignment keys so
both hit paths stay pinned.
`fn` was the short form of "function" from before this domain
became "assignment"; it no longer maps to the concept it names and
clouds intent at call sites. Apply Assignment-based names: short
`a` for parameters and locals (matching existing `func (a
*Assignment)` receivers), full `assignment` for struct fields and
compound identifiers (assignmentHeader, assignmentFilter,
defaultAssignment, etc.).

Genuine func-value callbacks in timer.Poll/Loop and the doclint
forEach* helpers keep `fn` -- there they name a function value,
not an Assignment.
@scott-rc scott-rc changed the title Audit docs and code prose for assignment vocabulary Audit assignment vocabulary in prose and code symbols May 11, 2026
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.

1 participant