Skip to content

Commit e979418

Browse files
os-zhuangclaude
andcommitted
docs(approvals): drop reserved word "role" from lifecycle copy (ADR-0090 D3)
#3113 added the approval-lifecycle walkthrough with 4 new occurrences of the reserved word "role", taking approvals.mdx from 5 → 9 and turning check:role-word red. Lint & Type Check has failed on every push to main since, so every open PR inherits a failing ESLint check. ADR-0090 D3 bans NEW occurrences — the --update path is for ratcheting the baseline DOWN — so the baseline stays at 5 and the copy is reworded instead. Three of the four were a duplicate: the new callout under "The request opens" restated the baselined `position` vs `role` callout ~80 lines above it, which already says the same thing in more detail (it names the os lint rule). Replaced with a cross-reference to it. The claim is also tightened to match expandApprovers(): an unresolvable entry does not leave `pending_approvers` empty, it falls back to a literal `<type>:<value>` slot that no user matches. The fourth documented `approverId` accepting `role:<r>`. That literal is real, but it is one of several (`team:` / `department:` / `position:` / `role:` / `manager:` per approval-service.ts), so naming only the `role:` form was both off-vocabulary and needlessly narrow. Generalized to `<type>:<value>` with a `position:finance_manager` example, matching the page's existing finance_manager sample. The surviving 5 are the documented D3 exception — the better-auth boundary (`sys_member.role`), which the `role` approver type genuinely resolves against via expandRoleUsers(). Verified: check:role-word exits 0 at 5 occurrences with the baseline untouched; eslint, check:doc-authoring, check:authz-resolver and check:release-notes pass; page rendered in the docs site — Steps block intact and the #3-the-approval-node cross-reference resolves. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent fdc244e commit e979418

1 file changed

Lines changed: 8 additions & 12 deletions

File tree

content/docs/automation/approvals.mdx

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -130,14 +130,10 @@ record is **locked** against edits while pending (`lockRecord`, default `true`),
130130
and the flow run parks until a decision arrives.
131131

132132
Only `approvers` is required on the node; everything else has a default
133-
(`behavior: 'first_response'`, `lockRecord: true`, `maxRevisions: 3`).
134-
135-
<Callout type="warn">
136-
**`type: 'role'` is not a position.** In an approver entry, `role` means the
137-
better-auth membership tier (`owner` / `admin` / `member`). Naming a business
138-
role like `sales_manager` there matches nobody and the request silently has no
139-
approvers — use `{ type: 'position', value: 'sales_manager' }`.
140-
</Callout>
133+
(`behavior: 'first_response'`, `lockRecord: true`, `maxRevisions: 3`). An
134+
approver entry that resolves to no users falls back to a literal `<type>:<value>`
135+
slot that no one matches, so the request opens and then stalls — see the
136+
approver-type warning under [The approval node](#3-the-approval-node).
141137

142138
### The approver finds it in their queue
143139

@@ -150,10 +146,10 @@ curl -b cookies.txt \
150146
"https://your-app.example.com/api/v1/approvals/requests?status=pending&approverId=usr_123"
151147
```
152148

153-
`approverId` accepts a user id, an email, or `role:<r>` — and takes several
154-
values (comma-separated or repeated) to cover a person's identities in one call.
155-
Other filters: `status`, `object`, `recordId`, `submitterId`, `q`, `limit`,
156-
`offset`.
149+
`approverId` accepts a user id, an email, or a `<type>:<value>` approver literal
150+
(`position:finance_manager`) — and takes several values (comma-separated or
151+
repeated) to cover a person's identities in one call. Other filters: `status`,
152+
`object`, `recordId`, `submitterId`, `q`, `limit`, `offset`.
157153

158154
<Callout type="warn">
159155
**Opening a request notifies nobody.** There is no built-in "you have an

0 commit comments

Comments
 (0)