docs(release): changelog, README, and copilot-instructions updates by YunchuWang · Pull Request #339 · microsoft/durabletask-js

YunchuWang · 2026-07-29T22:49:17Z

Splits the documentation and changelog updates out of #335. Zero runtime risk.

What (docs only)

CHANGELOG.md (root — core + azuremanaged notes)
packages/azure-functions-durable/CHANGELOG.md (compat)
packages/azure-functions-durable/README.md
.github/copilot-instructions.md

No runtime code changes.

Provenance

Content is byte-identical to the CI-green #335 branch at 8501bc0 — a pure re-partition, no behavior change.

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.

Split out of #335 as a standalone, independently reviewable change. Documentation-only updates supporting the per-package release: - CHANGELOG.md (root, core + azuremanaged) - packages/azure-functions-durable/CHANGELOG.md (compat) - packages/azure-functions-durable/README.md - .github/copilot-instructions.md No runtime code changes. Content is byte-identical to the CI-green #335 branch at 8501bc0; this is a pure re-partition with no behavior change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d86f5f69-4e1a-4c1d-b017-5e290c85cc05

Copilot

Pull request overview

Documentation-only PR that updates release notes and compat-package guidance for the durable-functions (Azure Functions) provider and the repo-wide changelog/Copilot instructions, aligning docs with current runtime semantics (e.g., whenAll wait-all behavior).

Changes:

Update durable-functions README guidance around removed v3 surfaces and add explicit Functions extension bundle requirements for gRPC.
Replace the compat package changelog placeholder with detailed preview/rewrite notes, requirements, breaking changes, and added features.
Update root changelog and Copilot instructions to reflect whenAll wait-all semantics and related breaking-change notes.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
`packages/azure-functions-durable/README.md`	Updates migration guidance and adds extension bundle requirements for the gRPC-based provider.
`packages/azure-functions-durable/CHANGELOG.md`	Replaces placeholder with detailed “Upcoming” preview/rewrite notes and compatibility/breaking-change documentation.
`CHANGELOG.md`	Adds breaking-change notes for `whenAll` semantics and default sub-orchestration instance ID derivation.
`.github/copilot-instructions.md`	Updates internal guidance to match current `WhenAllTask` wait-all behavior.

The azure-functions-durable CHANGELOG on main is a placeholder skeleton ("# Changelog" + "## TBD" + a "Details to be finalized" bullet), not the "## Upcoming"/"## v*" structure update-changelog.js expects. Because #337 and #339 are independently mergeable, this script must produce a clean changelog even if #337 lands first against that skeleton. Previously the first run prepended the new release sections and stranded the old skeleton at the bottom, yielding a confusing mixed-format file. Detect only that exact pristine skeleton (CRLF/LF tolerant) and swap in the standard empty Upcoming scaffold before the existing Upcoming parsing runs, so the placeholder bullet is never promoted into release notes and modern "## Upcoming" changelogs (core and the #339 compat rewrite) are unaffected. Addresses PR #337 review comment r3678561864. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d86f5f69-4e1a-4c1d-b017-5e290c85cc05

…revert changelogs per owner review Per repo-owner review on PR #339, the compat and root changelogs must not carry hand-authored narrative -- the release workflow/script generates their commit/message/PR entries at release time. Revert both to the origin/main baseline (root CHANGELOG.md and packages/azure-functions-durable/CHANGELOG.md are now byte-identical to origin/main; the compat file returns to the legacy `# Changelog` / `## TBD` skeleton that #337's updated script normalizes). Compat README (packages/azure-functions-durable/README.md): - Fix the entity-locking migration note. The classic `{ df, log }` context does not expose `entities`, so an orchestrator that needs locks must migrate to the core-native orchestrator/context shape first, then use `context.entities.lockEntities(...)` / `context.entities.isInCriticalSection()`. Link #317 (closed, not planned) as the decision record and drop the false "there is no tracking issue" claim. - Remove the verbose GA/Preview cross-feed comparison sentence from Requirements, keeping the required bundle ranges and the <= 4.32.0 gRPC warning. - Consolidate the preview/install guidance into `## Status`: the v4 provider is in preview under the `preview` npm dist-tag, install with `durable-functions@preview`, APIs may change before the GA `4.0.0` release. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d86f5f69-4e1a-4c1d-b017-5e290c85cc05

Copilot

Pull request overview

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

Comments suppressed due to low confidence (3)

packages/azure-functions-durable/README.md:47

The README implies context.entities.lockEntities(...) directly returns a LockHandle, but the core API returns a Task<LockHandle> that must be yielded (in an orchestrator) to obtain the handle. As written, this can mislead readers into calling release() on the task object rather than the resolved handle.

  the core-native orchestrator/context shape, then acquire locks with
  `context.entities.lockEntities(...entityIds)` (returns a `LockHandle` — call `release()`, ideally
  in a `finally`) and query with `context.entities.isInCriticalSection()`. Reintroducing the v3

packages/azure-functions-durable/README.md:191

The README states this provider is a preview of durable-functions v4 / 4.0.0, but packages/azure-functions-durable/CHANGELOG.md currently has no 4.0.0 section (it starts at v0.3.0). This makes the packaged changelog inconsistent with the published version and can confuse consumers looking for 4.0.0-breaking-change notes.

This rewritten `durable-functions` v4 provider is in **preview**, published under the `preview` npm
dist-tag — install it with `npm install durable-functions@preview`. APIs may change before the
GA `4.0.0` release.

.github/copilot-instructions.md:116

This updates the repo instructions to the correct wait-all semantics for WhenAllTask, but there is still contradictory documentation in code comments (e.g., packages/durabletask-js/src/task/index.ts currently says whenAll completes when one task fails). Please align those docs so contributors don't get mixed guidance.

    ├── WhenAllTask  — Completes when ALL children are terminal (waits for every child)

Follow-up on the rebase onto main (which now contains #337 + #339). Corrects doc/release_process.md so it matches the merged per-package release automation and the owner's #339 changelog decisions: - dist-tags: replace the misleading per-stage beta/next table + override note with the actual rule -- every prerelease publishes under a single `preview` dist-tag; a stable GA omits `--tag` and moves `latest`; git tags (v.../azuremanaged-v.../durable-functions-v...) are separate from npm dist-tags. Applied to both the Versioning Scheme and Quick Reference sections. - Prepare Release only prepares a branch/tag/changelog; its emitted `npm publish` command is a MANUAL FALLBACK. The sanctioned publish path is the ADO official build + ESRP release pipeline. - add a one-time azuremanaged tag preflight (seed azuremanaged-v0.3.0 from v0.3.0) so per-package changelog generation starts at v0.3.0 instead of the repo root -- no azuremanaged-v* tag exists yet, so the first run would otherwise fall back to the initial commit and dump the entire history. - Publishing Step 2: the official build (official-build.yml) triggers on and builds `main` -- it has no branch/tag selector and never builds the release branch; one main build packs all three .tgz into one drop; stage selection decides which package publishes. - Publishing Step 3: source artifact is the selected `main` official build (release.yml pins its build resource to branch: main); make explicit that core + compat need two release waves because the compat Prepare Release guard queries public npm for the exact core pin. - changelog wording: generated `### Changes` commit/PR entries, not hand-authored `### Breaking Changes`; preview/migration narrative lives in packages/azure-functions-durable/README.md; Quick Reference citation moved from the compat CHANGELOG to the README. - keep B11 as an explicit hard blocker for publishing durable-functions@ 4.0.0-beta.1 via ESRP; do not claim ESRP supports npm dist-tags. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d86f5f69-4e1a-4c1d-b017-5e290c85cc05

Copilot AI review requested due to automatic review settings July 29, 2026 22:49

This was referenced Jul 29, 2026

ci(release): per-package prepare-release workflow + changelog script #337

Merged

build(release): npm publishConfig for all three packages #338

Closed

Copilot started reviewing on behalf of YunchuWang July 29, 2026 22:49 View session

This was referenced Jul 29, 2026

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

Merged

Make prepare-release workflow per-package #335

Closed

Copilot AI reviewed Jul 29, 2026

View reviewed changes

Comment thread packages/azure-functions-durable/README.md Outdated

Comment thread packages/azure-functions-durable/CHANGELOG.md Outdated

YunchuWang commented Jul 30, 2026

View reviewed changes

Comment thread packages/azure-functions-durable/README.md Outdated

YunchuWang commented Jul 30, 2026

View reviewed changes

Comment thread CHANGELOG.md Outdated

YunchuWang commented Jul 30, 2026

View reviewed changes

Comment thread packages/azure-functions-durable/CHANGELOG.md Outdated

Copilot AI review requested due to automatic review settings July 30, 2026 18:08

Copilot started reviewing on behalf of YunchuWang July 30, 2026 18:09 View session

Copilot AI reviewed Jul 30, 2026

View reviewed changes

kaibocai approved these changes Jul 30, 2026

View reviewed changes

YunchuWang merged commit efc27d6 into main Jul 30, 2026
30 checks passed

YunchuWang deleted the release-docs branch July 30, 2026 18:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(release): changelog, README, and copilot-instructions updates - #339

docs(release): changelog, README, and copilot-instructions updates#339
YunchuWang merged 2 commits into
mainfrom
release-docs

YunchuWang commented Jul 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

YunchuWang commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What (docs only)

Provenance

Part of the #335 split

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

YunchuWang commented Jul 29, 2026 •

edited

Loading