docs: process documents and release tooling for the 1.0-beta release

[awatson1978]

This PR is the first step of the plan in #518. It adds the process documents and the release tooling for the 1.0-beta release. Merge of this PR publishes nothing.

Process documents

• .github/PULL_REQUEST_TEMPLATE.md sets what a PR description must have. A small staging PR fills in the summary and the checklist only. Each package merge into 1.0-beta fills in all sections: a runnable example, test evidence, benchmarks where the PR claims a performance change, and fixture citations.
• DATACITATION.md records the origin and the license of each committed DICOM test file. The format follows the file of the same name in OHIF. The origin of the six older test/*.dcm files is not known yet. The planned @dcmjs-org/fixtures work traces these files, or replaces them with synthetic files (RELEASE_PLAN.md, section 6, step 2).

Release tooling

All packages release together, with one shared version number:

1. semantic-release reads the commit titles and selects the next version.
2. scripts/stamp-workspace-versions.mjs writes that version into the root package and into each public workspace package. The script skips private packages.
3. pnpm -r publish publishes all public packages. On 1.0-beta, the packages go to the npm beta tag.

The changes:

• .releaserc.json sets three release branches: master, 1.0-beta (prerelease beta), and release/0.5x (range 0.x). The @semantic-release/npm plugin only sets the version and does not publish. The @semantic-release/exec plugin runs the stamp script and pnpm -r publish.
• .github/workflows/publish-package.yml now also runs on a push to 1.0-beta and to release/0.5x. The workflow loads @semantic-release/exec, and sets NODE_AUTH_TOKEN from NPM_TOKEN, because pnpm publish reads that variable.
• package.json marks the root dcmjs package "private": true on this branch. A recursive publish thus cannot publish the unscoped dcmjs name by accident (RELEASE_PLAN.md, section 9).
• test/stamp-workspace-versions.test.js has two tests. The first test stamps a scratch workspace and makes sure that the script skips private packages. The second test makes sure that the script rejects a string that is not a version, and changes no file.

Corrections to RELEASE_PLAN.md

• Section 3 now says that the plan first hoped for the @dcmjs/ scope. An earlier rename to @dcmjs-org also changed this historical sentence by mistake.
• Section 12, item 3 now tells the repository owner to register the @dcmjs-org npm organization, if necessary. The item also tells the owner to make sure that NPM_TOKEN can publish new packages under @dcmjs-org. The old item named the @dcmjs scope.

Before the first publish

The publish GitHub environment still controls the workflow. The workflow cannot run from 1.0-beta until the repository owner does the actions in RELEASE_PLAN.md, section 12:

1. Add branch protection to 1.0-beta.
2. Add 1.0-beta to the allowed branches of the publish environment.
3. Register the @dcmjs-org npm organization, if necessary, and make sure that NPM_TOKEN can publish under that scope.

An earlier version of this PR also added docs/WRITING_STYLE.md. Commit 2a5935e removed that guide, because the authoring work is complete.

🤖 Generated with Claude Code

[wayfarer3130]

There were three things found that I htink are worth looking at:

1. --tag beta on master after GA (Medium)
   .releaserc.json declares three branches: release/0.5x, master, and 1.0-beta. The publishCmd uses --tag beta on all of them. semantic-release reads the config from the branch that it builds, so only the master entry has an effect:

Before GA: no effect, because the file is only on 1.0-beta.
release/0.5x: no effect. That branch comes from the 0.52 line and does not have this file.
At GA, 1.0-beta merges into master. The first master publish is 1.0.0 with the beta dist-tag, and latest stays on 0.52.0. RELEASE_PLAN §10 says that GA "releases 1.0.0 to npm latest". The config does not do that. Each later master release also gets beta.
Recovery is easy: npm dist-tag add dcmjs@1.0.0 latest. Suggested fix, so that the GA PR needs no change to the config: --tag ${nextRelease.channel || 'latest'}.

2. The version can be 0.53.0-beta.1 (High, PLAUSIBLE)
   The last tag on 1.0-beta is v0.52.0. semantic-release calculates the prerelease from the last release and the commit types. A feat: commit gives 0.53.0-beta.1. A fix: commit gives 0.52.1-beta.1. Only a BREAKING CHANGE: footer (or feat!:) gives 1.0.0-beta.1. The plan says 1.0.0-beta.N everywhere, but no document tells the author to add a breaking-change commit. I did not run semantic-release to confirm this, because a dry run needs tokens.

Suggested fix: write the step in RELEASE_PLAN §9 (for example, the first package merge has a BREAKING CHANGE: footer). Or run semantic-release --dry-run --branches 1.0-beta to confirm.

3. Unscoped dcmjs is published during the beta (Medium)
   pnpm-workspace.yaml lists only ".". The root package is dcmjs, and it is not private. I ran a dry run in a scratch workspace with the same layout: pnpm -r publish includes the root package. So the first beta publish is dcmjs@-beta.1, with the beta tag.

RELEASE_PLAN §3 and §9 say that the beta publishes as @dcmjs/dcmjs, and that "the unscoped dcmjs name starts publishing ... when the team decides it is ready." The beta tag does not change latest, so users that do nothing are safe. But the plan and the config disagree. Ask the author which result is correct, and change the other one.

4. No dist-tag promotion (Medium)
   @semantic-release/npm has npmPublish: false, and @semantic-release/exec has no addChannelCmd. When semantic-release adds an existing version to a new channel, it calls addChannel. With this config, that step does nothing. Example: the cleanup of the vNext and dev tags in §10 must be done by hand. If that is the intent, the plan must say so.

[wayfarer3130]

A few comments,
also dcmjs is already claimed, by "dcmjs", which might be Steve, or it might be whoever registered the other dcmjs github (whcih hasn't done anything)

[awatson1978]

Thanks Bill — all four are addressed on this branch (and flowing to the staging branches):

1. --tag beta after GA — took your suggested fix verbatim: the publish command now tags with ${nextRelease.channel || 'latest'}, so the 1.0-beta branch publishes under beta and master publishes under latest with no config change needed in the GA PR. Appendix A in RELEASE_PLAN.md updated to match.

2. 0.53.0-beta.1 risk — you're right about the calculation; RELEASE_PLAN §9 now states the requirement explicitly: the release that produces the first beta must carry a BREAKING CHANGE: footer (or feat!:) so the computed version is 1.0.0-beta.1, plus a note to confirm with semantic-release --dry-run before flipping the publish switch.

3. Unscoped dcmjs during the beta — the plan's intent was the correct side, so the config changed: the root package.json is now "private": true on this lineage, which makes pnpm -r publish skip it. The wrapper PR (step 7 of the landing order) removes the flag when it renames the root surface to @dcmjs/dcmjs. §9 documents this.

4. No dist-tag promotion — manual is indeed the intent for now; §10 says so explicitly (channel tags come from the publish itself; promoting an existing version and deleting the stale vNext/dev tags is a hand-run npm dist-tag step, and an addChannelCmd is deferred until there's a real promotion to perform).

🤖 Generated with Claude Code

[wayfarer3130]

@awatson1978 - can you update the notes to indicate we will publish to @dcmjs-org/ paths and will reconsider if we can get the @dcmjs path later? I've contacted the owner of that, but don't have a response yet.

[awatson1978]

Done — everything now reads @dcmjs-org/. RELEASE_PLAN's scope-name note records the decision the way you described it: we publish under @dcmjs-org/ (matching the GitHub org), you've contacted the owner of @dcmjs, and if that name becomes available the team can reconsider the shorter scope later. The rename is applied end to end, not just in the notes: the package names, workspace dependencies, and by-name imports on the staging branches (#568 for the engine packages, #569 for schemas/fixtures), the data-citation file, and the assembly PR descriptions. The wrapper's beta name in §9 is now @dcmjs-org/dcmjs accordingly. One leftover action from §3 still stands: confirming the @dcmjs-org npm organization itself is registered to us before the first publish.

🤖 Generated with Claude Code

[wayfarer3130]

Just a few changes for better security/publishing design - note that trusted publishing will become required in 2027, so we might as well go with it.

• Raise minimumReleaseAge to 2880 (2 days).
• Pin semantic-release and its plugins as exact devDependencies.
• Pin each action by commit SHA.
• Publish with OIDC trusted publishing instead of the long-lived npm token.
• Turn off cache: pnpm in the publish job.

[awatson1978]

All five are in (fe4c87e) — agreed on getting ahead of the 2027 requirement rather than migrating later:

1. minimumReleaseAge 2880 — raised in pnpm-workspace.yaml (strict mode already on, so resolution fails loudly rather than falling back).

2. semantic-release pinned as exact devDependencies — semantic-release 25.0.9 plus all five plugins from .releaserc.json (commit-analyzer 13.0.1, release-notes-generator 14.1.1, npm 13.2.0, github 12.0.10, exec 7.1.0), exact like the rest of the devDependencies block, resolved through the lockfile. This also retired cycjimmy/semantic-release-action and its runtime-fetched extra_plugins — the publish step is now pnpm exec semantic-release, so nothing is fetched at release time.

3. Actions pinned by commit SHA — checkout, pnpm/action-setup, and setup-node, each with the version as a trailing comment.

4. OIDC trusted publishing — NPM_TOKEN/NODE_AUTH_TOKEN are gone, and so is setup-node's registry-url (its generated .npmrc expects a token env that no longer exists). The workflow already carried id-token: write for provenance; pnpm picks up the OIDC exchange from there. RELEASE_PLAN §12 now documents the owner side: register each package's trusted publisher on npmjs.com (this repo + publish-package.yml + the publish environment) — including the first-publish bootstrap, since a trusted publisher can only be configured on a package that already exists, the very first publish of each new package is a one-time npm publish from an owner workstation.

5. cache: pnpm off in the publish job — removed; the job installs from the lockfile only.

Appendix B in RELEASE_PLAN now states the whole hardening posture in one place so it survives after this PR's conversation.

🤖 Generated with Claude Code

[awatson1978]

The audit failure after the previous push had a root cause worth recording: pnpm 11 stopped reading package.json pnpm.overrides (it had been warning on every install), so this branch's security pins had silently stopped applying — regenerating the lockfile for the semantic-release devDependencies surfaced it (form-data@3 and ws@7 resolving to advisory-vulnerable versions through jest's jsdom chain). f2a3631 ports the fix already on release/1.0-beta-core: the overrides live in pnpm-workspace.yaml where pnpm 11 reads them, the dead package.json field is removed, and the braces GHSA ignore stays (the advisory's "patched" 3.0.4 still doesn't exist on the registry — re-checked today; all paths are dev tooling). pnpm audit --audit-level=high exits 0 and the suite is 320/320; all checks green.

🤖 Generated with Claude Code