vercel / vercel/workflow

code-transform.mdx §ID Generation omits the package-shipped `name@version` ID form

Open Beginner friendly
#3,154 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
2.4k
Forks
365
Avg merge
2d 11h
Merged PRs (30d)
169

Description

Summary

how-it-works/code-transform.mdx §"ID Generation" (v4:309-329, v5:311-329) documents only the local-file ID form {type}//{filepath}//{functionName} and never mentions the package-shipped form {type}//{name}/{subpath}@{version}//{functionName} (produced by packages/builders/src/module-specifier.ts:370-402 for export-reachable package files).

Not wrong, but incomplete in exactly the direction that made the #3152 error plausible: a reader learns IDs come from file paths, so "re-export into my workflows/ dir → my path → my ID" is a natural inference — the same inference #3153 corrects in publishing-libraries.mdx.

Suggested fix

Add the package-shipped form to the ID Generation section, next to the local-file form, with one line on when each applies (workspace/local files vs. export-reachable npm package files). The section's existing callout already states deployment pinning correctly ("changing IDs won't break old workflows from running, but will prevent runs from being upgraded"), so only the ID-form table/list needs the addition.

Related: #3152, #3153. Found during a docs sweep while building the Mastra integration.

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

Open how-it-works/code-transform.mdx and locate the “ID Generation” section at v4:309-329 or v5:311-329. Compare its local-file form with the package-shipped form produced in packages/builders/src/module-specifier.ts:370-402, then document when each applies to make the section complete.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.