Skip to content

Docs and skills: the Join helper and the updated Workflow Patterns ratings - #1594

Merged
longquanzheng merged 10 commits into
mainfrom
docs/join-helper
Nov 11, 2026
Merged

longquanzheng merged 10 commits into
mainfrom
docs/join-helper

Conversation

@longquanzheng

Copy link
Copy Markdown
Contributor

Summary

Documents the Join helper (SDK 1.44.0) and updates the Workflow Patterns evaluation, the Await design pattern, Concepts, the SDK waits references, and skills.

  • Workflow Patterns evaluation (en and zh-Hans): an SDK API that all five SDKs provide and the docs present as the standard form counts as one Dex construct. 14 patterns move from +/- to + (WCP-3, 7, 9, 13, 14, 28, 29, 30, 31, 32, 34, 35, 37, 41); totals go from 19 + / 24 +/- to 33 + / 10 +/-. "Why many joins are indirect" becomes "How Dex joins parallel branches" (anchor kept) and explains why the remaining ten stay +/-. A new "Limits of the Join" section states the rules (each branch reports exactly once, including failure routes; an externally cancelled branch stalls an all-of join, with two workarounds; a cancelled join Step's matched results depend on the server version).
  • Await design pattern (en and zh-Hans): text follows the generated Flow graph; all five language tabs are copied from the migrated examples on main (fixing earlier drift); new "Rules" and "Wait for some branches" sections. The Parallel index line is updated.
  • Concepts (Channel "When to use", Step "Waiting", en and zh-Hans): one sentence each pointing to the Join, built on a ChannelMap.
  • Developer reference: each SDK's waits page gains "Join parallel branches" (Since 1.44.0) linking the API reference, the Await page, and the examples. The server 0.1.26 change log gains the missing entry for requeuing consumed messages when a Step is cancelled (server-zd: return a canceled Step's consumed messages and wake waiters after cancellations #1465).
  • examples/workflow-patterns-mapping.md: ratings, totals, and the specs and assertions of the migrated Flows.
  • Skills 1.1.0 (stable content: the Await pattern and new join rules): Await skeleton with fork / end branch / for all branches and its rules; a new "Partial join and reset" section; control structure rows; channel.md points joins to the Join; language skeletons copied from examples.

Why

The owner approved the Join helper design (D1-D6). The helper shipped in 1.44.0 in all five SDKs (#1549, #1550, #1552, #1553, #1554) and the examples moved to it (#1577, #1579, #1580, #1582, #1583). This PR is the docs and skills half of design sections 6, 10.2, and 10.3.

Follow-ups: #1590 (generated API reference still at 1.37.0, so Java/TypeScript Join links 404 until it refreshes), #1591, #1592.

Testing

  • cd docs && npm run check; skills check-package.py, check-doc-map.py (also with --base-ref origin/main), skills unit tests (60), version-check tests (11); every GitHub example path referenced exists on main.
  • npm run generate:flow-definitions: no change.
  • Read top to bottom in a browser, in English and Simplified Chinese: Workflow Patterns evaluation, Await Parallel Steps, Parallel Steps index, Channel concept, Step concept. Each checked in a 390px iframe without horizontal scroll.

@longquanzheng
longquanzheng enabled auto-merge (squash) November 11, 2026 04:52
@longquanzheng
longquanzheng merged commit 698001d into main Nov 11, 2026
4 checks passed
@longquanzheng
longquanzheng deleted the docs/join-helper branch November 11, 2026 05:00
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