docs(release): rewrite release_process.md for the per-package model

[YunchuWang]

Splits the release-runbook rewrite out of #335.

What

Rewrites doc/release_process.md for the per-package release model:

• per-package independent versioning, changelogs, and tags;
• the one hard ordering constraint — core must publish before durable-functions (compat exact-pins @microsoft/durabletask-js), while @microsoft/durabletask-js-azuremanaged is unordered (peer floor >=0.3.0 already satisfied by published core);
• ESRP via eng/ci/release.yml documented as the sanctioned publish path, with its three individually-selectable per-package stages;
• the required package workflow input and prefix-derived branch/tag names;
• the durable-functions@preview dist-tag.

Whether ESRP can set an npm dist-tag is written as an explicit open action item, not asserted as fact.

Provenance

doc/release_process.md content is byte-identical to #335's runbook commit c602302.

---

Part of the #335 split

#335 is being decomposed into four mutually independent PRs that can merge in any order:

• ci(release): per-package prepare-release workflow + changelog script #337 — per-package prepare-release workflow + changelog script
• build(release): npm publishConfig for all three packages #338 — npm publishConfig (smallest; most urgent for publishing)
• docs(release): changelog, README, and copilot-instructions updates #339 — changelog / README / copilot-instructions docs
• docs(release): rewrite release_process.md for the per-package model #340 — release_process.md runbook rewrite

Together these carry every one of #335's 10 files with no overlap. #335 stays open until the file→PR mapping posted there is confirmed; these PRs neither merge nor close it.

[Copilot]

Pull request overview

Updates the release runbook (doc/release_process.md) to describe a per-package release model for this monorepo, including the ESRP-based publish path and package-specific tagging/versioning expectations.

Changes:

• Expands the runbook scope from two packages to three (core, azuremanaged, and durable-functions) and documents per-package versioning/tagging.
• Documents publish ordering constraints (core before durable-functions) and ESRP release pipeline stage behavior (eng/ci/release.yml).
• Adds guidance around prerelease dist-tags (notably preview) and verification commands.

Comments suppressed due to low confidence (3)

doc/release_process.md:49

• The runbook says the Prepare Release workflow has a required package input, but the current .github/workflows/prepare-release.yaml only accepts a version input and bumps both durabletask-js and durabletask-js-azuremanaged together. If this doc is intended to merge independently of the per-package workflow change, this step should either be conditional or call out the prerequisite explicitly.

3. **Select the `package` to release** (required) — one of `durabletask-js`, `durabletask-js-azuremanaged`, or `azure-functions-durable`. Each run releases exactly one package.

doc/release_process.md:237

• This bullet claims the Prepare Release workflow's run summary suggests an npm publish ... --tag preview command, but the current workflow summary only prints version/branch/tag and a Create PR link; it doesn't mention npm publish or dist-tags. This should be phrased as manual guidance (or gated on the per-package workflow update).

- The **Prepare Release** workflow publishes *every* prerelease (any version containing `-`) under the single **`preview`** dist-tag — its run summary suggests `npm publish --registry https://registry.npmjs.org/ --tag preview` — so a prerelease never moves `latest`.

doc/release_process.md:43

• This section currently reads as if the repo already has the per-package Prepare Release workflow (package selection, package-scoped tags/branches, etc.), but .github/workflows/prepare-release.yaml in this branch is still the legacy workflow (single version input, bumps two packages, tags vX.Y.Z). Without an explicit prerequisite note, the runbook will be incorrect if merged before the workflow update.

Use the **Prepare Release** GitHub Action to automate the release preparation process.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

doc/release_process.md:62

• This section describes a per-package Prepare Release workflow (package-scoped tags/branches, changelog scoped to a package directory, durable-functions npm publish guard). The current .github/workflows/prepare-release.yaml does not do any of this: it generates the changelog from git log <latest-tag>..HEAD (no path scope), bumps both packages/durabletask-js and packages/durabletask-js-azuremanaged (and rewrites the azuremanaged peer dependency to >=$NEW_VERSION), writes only the repo-root CHANGELOG.md, and creates release/v<version> + v<version>. Either add an explicit prerequisite note that this section applies only after the per-package workflow lands, or update the bullets to match the workflow that currently exists.

For the **one package you selected** (and only that package):

1. **Determines the next version**: uses the `version` input, or auto-increments the selected package's current version
2. **Generates a changelog**: lists commits since that package's last release tag, scoped to the package's directory (`git log <last-tag>..HEAD -- <pkg-dir>`), so only commits that touched that package are included
3. **Bumps the version**: updates `version` in that package's own `package.json`
4. **Updates that package's changelog**: core and azuremanaged write the repo-root `CHANGELOG.md`; `durable-functions` writes `packages/azure-functions-durable/CHANGELOG.md`
5. **Creates a release branch and a package-scoped tag**: tag `<prefix><version>` and branch `release/<prefix><version>`, where the prefix is `v` (core), `azuremanaged-v`, or `durable-functions-v`
6. **For `durable-functions` only**: verifies the exact-pinned `@microsoft/durabletask-js` version is already published on public npm, and fails the run if it is not (guards the uninstallable-dependency case)

doc/release_process.md:239

• These bullets again state that the Prepare Release workflow emits npm publish ... --tag preview and that durable-functions 4.x previews are documented as npm install durable-functions@preview in packages/azure-functions-durable/CHANGELOG.md. In the current repo, the workflow summary does not emit a publish command, and the compat package changelog is currently just ## TBD with no preview install guidance. This should be rewritten to avoid referencing behavior/docs that aren’t present yet.

- The **Prepare Release** workflow prescribes publishing *every* prerelease (any version containing `-`) under the single **`preview`** dist-tag: its run summary emits `npm publish --registry https://registry.npmjs.org/ --tag preview` for you to run after the release PR merges — so a prerelease never moves `latest`.
- **`durable-functions` 4.x previews ship under `preview`.** Its documented install line is `npm install durable-functions@preview` (see `packages/azure-functions-durable/CHANGELOG.md`); publish these with `npm publish --tag preview`.
- Whether the **ESRP** pipeline (Step 3) can set a dist-tag is an open question (B11); the `--tag` guidance here applies to a manual `npm publish`.

doc/release_process.md:39

• This note asserts the Prepare Release workflow emits an npm publish … --tag preview command and that durable-functions previews ship under preview. In the current repo, .github/workflows/prepare-release.yaml does not emit any npm publish command (it only prints branch/tag/PR link), and packages/azure-functions-durable/CHANGELOG.md does not document durable-functions@preview (it currently only has a ## TBD placeholder). This guidance should be rewritten to avoid stating behavior that isn’t present in the repo yet.

This issue also appears on line 237 of the same file.

> Note: current tooling overrides the beta/rc rows above for prereleases. The **Prepare Release** workflow emits an `npm publish … --tag preview` command (in its run summary, to run after the release PR merges) for **any** prerelease version — any version containing `-` — so prereleases go out under the single `preview` dist-tag rather than `beta`/`next`; `durable-functions` 4.x previews ship under `preview` (`npm install durable-functions@preview`). See *Quick Reference: npm Dist Tags* below.

doc/release_process.md:51

• The docs say the Prepare Release workflow requires selecting a package input and gives durable-functions-specific version examples. In the current .github/workflows/prepare-release.yaml, the only workflow_dispatch input is version, and the workflow always bumps both durabletask-js and durabletask-js-azuremanaged together. Please make these steps conditional (or add a prerequisite note) so the runbook stays accurate until the per-package workflow is actually present.

This issue also appears on line 55 of the same file.

3. **Select the `package` to release** (required) — one of `durabletask-js`, `durabletask-js-azuremanaged`, or `azure-functions-durable`. Each run releases exactly one package.
4. Optionally specify a version (e.g., `0.2.0-beta.1` for core, or `4.0.0-beta.1` for `durable-functions`). Leave empty to auto-increment the selected package's current version (bumps the prerelease number for a prerelease, otherwise the patch).
5. Click **Run workflow**

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (5)

doc/release_process.md:133

• Same as earlier: “B11” is not defined anywhere in-repo, so the label doesn’t help the reader. Consider removing the internal label (or defining it) while keeping the warning.

> **Open question (B11) — hard blocker for ESRP prereleases:** it is not yet confirmed whether the ESRP release task can set the npm **dist-tag** (e.g. publish a prerelease under `preview` rather than moving `latest`). Publishing a prerelease such as `durable-functions@4.0.0-beta.1` through ESRP is **blocked** until the ESRP / 1ES pipeline owners confirm how to apply the `preview` tag — do **not** assume ESRP applies a dist-tag. The `--tag` guidance in *Quick Reference: npm Dist Tags* applies to a manual `npm publish`.

doc/release_process.md:242

• “Open question (B11)” uses an internal label that isn’t defined elsewhere in the repo. Dropping the label (or defining it) would make this quick reference clearer to future maintainers.

- **ESRP path (sanctioned, Step 3):** whether the ESRP release task can set an npm dist-tag is an **open question (B11)** and a **hard blocker** for publishing a prerelease such as `durable-functions@4.0.0-beta.1` through ESRP — confirm with the ESRP / 1ES owners how to apply the `preview` tag before publishing any prerelease via ESRP. Do **not** assume ESRP applies a dist-tag; the `--tag preview` guidance above is for a manual `npm publish`.

doc/release_process.md:39

• The reference to “B11” is unclear/undefined in this repo, which makes this prerequisite hard to interpret for maintainers. Consider removing the internal label (or defining it explicitly) and state the dependency in plain terms.

This issue also appears in the following locations of the same file:

• line 133
• line 242

The scheme above describes the version **string**. Mapping a version to an **npm dist-tag** is a separate concern and does **not** follow a per-stage `beta`/`next` convention: the **Prepare Release** workflow's emitted **manual fallback** `npm publish` command tags every prerelease `preview` and omits `--tag` for a stable GA (so only a GA moves `latest`). Publishing a prerelease through the sanctioned ESRP path is **blocked pending B11** until owners confirm whether the ESRP task can set that tag. See *Quick Reference: npm Dist Tags* below for the authoritative rule.

doc/release_process.md:102

• This sentence claims the official build “has no branch/tag selector and never builds” the release branch. The YAML shows it triggers on main, but it can still be manually queued on other branches; the more important constraint is that the release pipeline consumes artifacts from main (resource pinned to branch: main). Rewording avoids an absolute statement that may be inaccurate.

Trigger the official build pipeline to produce signed `.tgz` artifacts. The official build (`eng/ci/official-build.yml`) triggers on and builds **`main`** — it has no branch/tag selector and never builds the short-lived release branch. Use (or pick the automatic run of) the official build whose source commit **includes the merged release commit(s)**:

doc/release_process.md:123

• Leaving “ADO pipeline link: TBD” makes this step non-actionable in practice. If the link can’t be provided yet, it’s clearer to omit the placeholder (or replace it with concrete navigation instructions / a tracked issue).

**Pipeline**: `eng/ci/release.yml` (ADO pipeline link: TBD)