[Internal] Changelog: Adds per-PR Unreleased pattern; retires in-repo release-copilot-agent

.github/copilot-instructions.md

@@ -48,6 +48,64 @@ Purpose: quick, actionable context so an AI coding assistant can be immediately
     - `[v4] Client Encryption: Refactors code to external project`
     - `[Internal] Query: Adds code generator for CosmosNumbers for easy additions in the future`
   - Keep changes minimal and focused; prefer small, targeted edits and follow existing code style.
+  - **Changelog entry required**: Every PR that modifies the shipped package
+    source (anything under `Microsoft.Azure.Cosmos/src/**`, equivalent paths
+    for FaultInjection / Encryption packages) must also add a bullet under
+    `### Unreleased` in `changelog.md`, in one of the four subsections
+    `Features Added` / `Breaking Changes` / `Bugs Fixed` / `Other Changes`.
+    Write the entry in **customer-facing language** — not the PR title
+    verbatim. If the change has zero customer-observable impact (test-only,
+    doc-only, CI-only, purely internal refactor), check the "No changelog
+    entry required" box in the PR template and justify briefly. If a
+    preview-only change might affect default-config semantics for any
+    customer in the next two minor releases, it does **not** qualify as
+    purely internal — it goes under `Other Changes` (or `Bugs Fixed` /
+    `Breaking Changes` as appropriate).
+  - **Changelog classifier** (apply when uncertain whether an entry is required):
+
+    1. Does the PR diff touch any of:
+       - `Microsoft.Azure.Cosmos/src/**`
+       - `Microsoft.Azure.Cosmos/FaultInjection/src/**`
+       - any other shipped-package source tree?
+
+       *No* ⇒ no entry required. Done.
+       *Yes* ⇒ continue.
+
+    2. Could a customer observe the change by upgrading the SDK and
+       running their existing workload (no code change on their side)?
+       Consider: behavior, return values, error shape, latency,
+       memory/CPU profile, allocation patterns, surfaced types, public
+       API.
+
+       *Yes* ⇒ **entry required**. Pick the subsection:
+         - New customer-opt-in functionality ⇒ `Features Added`
+         - Behavior change that could break customer expectations on upgrade ⇒ `Breaking Changes`
+         - Customer-observable defect fixed ⇒ `Bugs Fixed`
+         - Performance / dependency / observable-but-not-categorized ⇒ `Other Changes`
+
+       *No* (test-only, CI-only, doc-only, pure internal refactor that
+       passes the next test) ⇒ no entry required. Document the omission
+       in the PR description.
+
+    3. **Preview-feature carve-out.** If the change is to a preview-only
+       code path *and* it could affect default-config semantics for any
+       customer in the next two minor releases, treat it as customer-
+       observable and require an entry under `Other Changes`. PR #5310
+       (PPAF dynamic enablement preview that affected default-config
+       memory) is the canonical example.
+
+    4. **Unsure after applying steps 1–3?** Default to **leaving a
+       non-blocking comment** on the PR asking the reviewer to confirm:
+
+       > "Changelog classifier outcome is ambiguous for this diff
+       > (touches shipped src but customer impact unclear). Defaulting
+       > to **no entry**; please verify and add one if needed."
+
+       Do **not** silently skip an entry on an ambiguous case — the
+       comment is the signal.
+
+    This rubric is mirrored in `CONTRIBUTING.md` (the human-author
+    audience). The two must stay in sync.
   - When suggesting build/test changes, reference the relevant MSBuild property or pipeline YAML (point to `Directory.Build.props` or `templates/*`).
   - Do not change version numbers or packaging settings without explicit instruction — these are centrally managed.
   - If adding or modifying tests that require the emulator, include/update relevant CI/template steps and document required environment variables.
@@ -60,10 +118,7 @@ Purpose: quick, actionable context so an AI coding assistant can be immediately
   - **IssueFixAgent** (`.github/agents/issue-fix-agent.agent.md`) — Comprehensive workflow for triaging and fixing GitHub issues. Use `@IssueFixAgent` in VS Code Copilot Chat or follow the plan manually.
   - Includes: environment setup, issue investigation, fix implementation, testing requirements, PR workflow, and learnings capture.
   - Start with: `@IssueFixAgent investigate issue #XXXX` or see Quick Start in the agent file.
-  - **ReleaseCopilotAgent** (`.github/agents/release-copilot-agent.agent.md`) — Guides the team through full releases and hotfix releases of the Cosmos DB .NET SDK. Automates changelog generation, version bumping, API contract file generation (GenAPI), and PR creation.
-  - Three modes: **Minor Mode** (full GA + Preview release), **Hotfix Mode** (cherry-pick patch release on any previous version), and **Add Missed PRs** (add PRs that were missed in a previous changelog).
-  - In VS Code Copilot Chat: `@ReleaseCopilotAgent start minor`, `@ReleaseCopilotAgent start hotfix`, or `@ReleaseCopilotAgent add missed PRs`.
-  - In the Copilot CLI: describe the task naturally (e.g., "I want to start a minor release", "start hotfix", or "I need to add missed PRs to a release"). The agent instructions are loaded automatically via this file.
+  - **Release flows** for the Cosmos DB .NET SDK + Microsoft.Azure.Cosmos.FaultInjection package live in the [cosmos-sdk-copilot-toolkit](https://github.com/Azure/cosmos-sdk-copilot-toolkit) under skills `cosmos-release-dotnet` (main SDK: minor / hotfix / add-missed-PRs modes) and `cosmos-release-dotnet-faultinjection` (FaultInjection package). The in-repo `release-copilot-agent.agent.md` was retired to avoid drift; both skills are the canonical source. In the Copilot CLI: describe the task naturally ("start a minor release", "release fault injection beta", etc.) — the routing agent loads the right skill automatically.
   - **MsdataDirectSyncAgent** (`.github/agents/msdata-direct-sync-agent.agent.md`) — Orchestrates syncing the msdata/direct branch with the latest v3 main and msdata direct codebase.
   - In VS Code Copilot Chat: `@MsdataDirectSyncAgent sync msdata/direct`.
   - In the Copilot CLI: describe the task naturally (e.g., "sync the msdata/direct branch with main").

.github/workflows/changelog-check.yml

@@ -0,0 +1,70 @@
+name: Changelog Check (soft, non-blocking)
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+    paths:
+      - 'Microsoft.Azure.Cosmos/src/**'
+      - 'Microsoft.Azure.Cosmos/FaultInjection/src/**'
+      - 'changelog.md'
+      - 'Microsoft.Azure.Cosmos/FaultInjection/changelog.md'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  changelog-soft-check:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.pull_request.labels.*.name, 'no-changelog-needed')"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect which packages were touched
+        id: detect
+        run: |
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+          CHANGED=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")
+
+          MAIN_SRC=$(echo "$CHANGED" | grep -E '^Microsoft\.Azure\.Cosmos/src/' || true)
+          FI_SRC=$(echo "$CHANGED"   | grep -E '^Microsoft\.Azure\.Cosmos/FaultInjection/src/' || true)
+          MAIN_CL=$(echo "$CHANGED" | grep -E '^changelog\.md$' || true)
+          FI_CL=$(echo "$CHANGED"   | grep -E '^Microsoft\.Azure\.Cosmos/FaultInjection/changelog\.md$' || true)
+
+          MAIN_MISSING=$([[ -n "$MAIN_SRC" && -z "$MAIN_CL" ]] && echo "true" || echo "false")
+          FI_MISSING=$([[ -n "$FI_SRC" && -z "$FI_CL" ]]     && echo "true" || echo "false")
+
+          echo "main_missing=$MAIN_MISSING" >> "$GITHUB_OUTPUT"
+          echo "fi_missing=$FI_MISSING"     >> "$GITHUB_OUTPUT"
+
+      - name: Post (or update) soft-check comment
+        if: steps.detect.outputs.main_missing == 'true' || steps.detect.outputs.fi_missing == 'true'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: changelog-soft-check
+          message: |
+            ## :memo: Changelog reminder (non-blocking)
+
+            This PR touches shipped source but does not appear to update the
+            corresponding `changelog.md`.
+
+            Touched (and missing entry for):
+            ${{ steps.detect.outputs.main_missing == 'true' && '- `Microsoft.Azure.Cosmos/src/**` ⇒ expected an entry in `changelog.md` (`### Unreleased`)' || '' }}
+            ${{ steps.detect.outputs.fi_missing == 'true'   && '- `Microsoft.Azure.Cosmos/FaultInjection/src/**` ⇒ expected an entry in `Microsoft.Azure.Cosmos/FaultInjection/changelog.md` (`### Unreleased`)' || '' }}
+
+            ### How to decide
+
+            Use the rubric in `.github/copilot-instructions.md` ("Changelog
+            classifier") or in `CONTRIBUTING.md` ("Changelog entry"). Quick
+            version:
+
+            - Customer-observable change (behavior, perf, memory, API) ⇒ **add an entry**, even if the PR is `[Internal]`.
+            - Test-only / CI-only / doc-only / pure-internal-refactor with zero customer-observable effect ⇒ no entry, add the `no-changelog-needed` label to silence this check.
+            - **Unsure?** Default to adding a one-line entry under `#### Other Changes`. Reviewer will adjust.
+
+            This check is **non-blocking** — merge is not gated on it. The
+            reviewer is responsible for the final classification.

.github/workflows/prlint.yml

@@ -20,9 +20,9 @@ jobs:
         on-failed-regex-create-review: true
         on-failed-regex-comment: >
          Please follow the required format: \"[Internal] Category: (Adds|Fixes|Refactors|Removes) Description\"<br /><br />
-         Internal should be used for PRs that have no customer impact. This flag is used to help generate the changelog to know which PRs should be included.
+         The `[Internal]` prefix is a review hint indicating no customer-observable impact (test pipelines, CI, doc-only changes, pure internal refactors). It does **not** affect changelog generation — the changelog is maintained per-PR in `### Unreleased` of `changelog.md`. See CONTRIBUTING.md for the full `[Internal]` definition and the preview-feature carve-out.
          Examples:<br />
-         Diagnostics: Adds GetElapsedClientLatency to CosmosDiagnostics<br/> 
-         PartitionKey: Fixes null reference when using default(PartitionKey)<br/> 
+         Diagnostics: Adds GetElapsedClientLatency to CosmosDiagnostics<br/>
+         PartitionKey: Fixes null reference when using default(PartitionKey)<br/>
          [v4] Client Encryption: Refactors code to external project<br/>
          [Internal] Query: Adds code generator for CosmosNumbers for easy additions in the future.<br/>

.gitignore

@@ -331,3 +331,6 @@ ASALocalRun/
 
 # Visual Studio Code files
 .vscode/
+
+# Coding Agent Harness session artifacts (local-only)
+.coding-harness/

CONTRIBUTING.md

@@ -99,6 +99,109 @@ When evaluating adding new tests, please search in the existing test files if th
 1. Check for [test failures](#test-failures) and address them if they are not transient.
 1. Review the **Checks** section to confirm there are no pending steps that might be blocking your work from merging.
 
+## Changelog entry
+
+Every pull request that changes shipped behavior must add a changelog
+entry. This is the same pattern used by the Cosmos DB SDKs for Java
+(`azure-sdk-for-java/sdk/cosmos/azure-cosmos/CHANGELOG.md`) and Python
+(`azure-sdk-for-python/sdk/cosmos/azure-cosmos/CHANGELOG.md`).
+
+### Where to add it
+
+`changelog.md` has a `### Unreleased` section at the top of the "Release
+notes" block. Underneath are four subsections:
+
+- `#### Features Added` — new functionality customers can opt into.
+- `#### Breaking Changes` — anything that could break a customer's
+  build, behavior, or expectations on upgrade.
+- `#### Bugs Fixed` — defects fixed in shipped behavior.
+- `#### Other Changes` — behavioral or performance changes that
+  customers should know about but that aren't features or bugs.
+  Refactors with observable effects, dependency bumps with
+  customer-visible behavior changes, etc.
+
+Add your bullet under the matching subsection.
+
+If your PR touches `Microsoft.Azure.Cosmos/FaultInjection/src/**` instead
+of (or in addition to) the main SDK source, add your bullet to
+`Microsoft.Azure.Cosmos/FaultInjection/changelog.md` under its own
+`### Unreleased` section.
+
+### How to write it
+
+- One line per change.
+- Customer-facing language. The audience is the developer running
+  `dotnet add package Microsoft.Azure.Cosmos`, not a teammate
+  reviewing your PR.
+- Reference the PR by number with a link:
+  `See [PR 1234](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/1234).`
+- The PR title and the changelog entry are **not the same thing**. The
+  title is engineering shorthand; the entry is a release-note line.
+
+Example:
+
+| PR title (engineering) | Changelog entry (customer-facing) |
+|---|---|
+| `DocumentClient: Adds tests for PartitionKeyRangeLocation disposal` | `Fixes per-CosmosClient memory and CPU leak introduced in 3.53.0 by disposing GlobalPartitionEndpointManagerCore. See [PR 5778](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5778).` |
+
+### Default verb → subsection mapping
+
+When the change has no other obvious classification, use the verb in your
+PR title as a starting point:
+
+| PR title verb | Default subsection |
+|---|---|
+| `Adds` (customer-visible) | Features Added |
+| `Adds` (internal refactor, no observable effect) | Other Changes (often omit) |
+| `Fixes` (customer-visible defect) | Bugs Fixed |
+| `Removes` (public API removal) | Breaking Changes |
+| `Removes` (internal/private code) | Other Changes (often omit) |
+| `Refactors` | Other Changes (omit if no observable effect) |
+
+The verb regex enforced by `.github/workflows/prlint.yml` still governs
+the PR title, but the PR title no longer drives the changelog content.
+
+### When the `[Internal]` prefix is appropriate
+
+`[Internal]` in the PR title is reserved for changes with **no
+customer-observable impact**:
+
+- Test-pipeline / CI / build-tooling changes.
+- Internal refactors that do not change runtime behavior, allocations,
+  memory profile, CPU profile, or surfaced types.
+- Documentation-only changes inside the repo (not changelog).
+
+`[Internal]` is **not** appropriate for:
+
+- Any change to `Microsoft.Azure.Cosmos/src/**` that a customer could
+  observe by running their workload under different SDK versions, even
+  if the change is to an "internal" type. PR #5310 (PPAF dynamic
+  enablement, which changed `DocumentClient` reference semantics from
+  weak to strong) is the canonical anti-example — the change was
+  preview-internal but had load-bearing customer-observable effects.
+
+**Preview-feature carve-out:** if a preview-only change might affect
+default-config semantics for any customer in the next two minor
+releases, it does not qualify as `[Internal]` — it goes under
+`Other Changes` (or `Bugs Fixed` / `Breaking Changes` as appropriate).
+
+### What reviewers verify
+
+When reviewing a PR, check:
+
+1. The "Changelog" section of the PR description is filled in.
+2. If an entry was added: it is in the right subsection, the language
+   is customer-facing, and the bullet links to the PR.
+3. If the author chose "No changelog entry required": the justification
+   is genuine (test-only, doc-only, CI-only, or pure internal refactor
+   with no customer-observable effect).
+
+### Conflicts in `### Unreleased`
+
+If two PRs add bullets to the same subsection of `### Unreleased` you
+may see a merge conflict. Take both bullets — the order is not
+significant.
+
 ### Test failures
 
 If the Pull Request is experiencing test failures, these will appear as failed checks:

Microsoft.Azure.Cosmos/FaultInjection/changelog.md

@@ -5,24 +5,34 @@ This project is in beta. The API and functionality may change when the project i
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+### <a name="unreleased-faultinjection"/> Unreleased
+
+#### Features Added
+
+#### Breaking Changes
+
+#### Bugs Fixed
+
+#### Other Changes
+
 ### <a name="1.0.0-beta.1"/> [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.FaultInjection/1.0.0-beta.1) - 2026-04-30
 
-#### Added
+#### Features Added
 - [#4867](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/4867) FaultInjection: Adds method to add FaultInjection using CosmosClientBuilder
 - [#4989](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/4989) Metadata Requests: Adds Metadata request support for FaultInjection
 - [#5264](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5264) ThinClient Compatibility: Adds compatibility with Thin Client Proxy
 - [#5510](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5510) Unauthorized Errors: Adds Unauthorized status codes
 - [#5677](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5677) FaultInjection: Adds XML documentation, stylecop.json, and updates test packages
 - [#5679](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5679) FaultInjection: Adds comprehensive unit test coverage
 
-#### Fixed
+#### Bugs Fixed
 - [#5676](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5676) FaultInjection: Fixes naming typos and XML documentation
 - [#5675](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5675) FaultInjection: Fixes critical bugs for release 2
 - [#5678](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5678) FaultInjection: Refactors code quality improvements
 
 ### <a name="1.0.0-beta.0"/> [1.0.0-beta.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.FaultInjection/1.0.0-beta.0) - 2024-11-15
 
-#### Added
+#### Features Added
 
 - Support for fault injection in the Cosmos SDK.
 - Support for fault injection in Direct Mode.

PULL_REQUEST_TEMPLATE.md

@@ -15,4 +15,16 @@ Please delete options that are not relevant.
 
 ## Closing issues
 
-To automatically close an issue: closes #IssueNumber
+To automatically close an issue: closes #IssueNumber
+
+## Changelog
+
+- [ ] I have added a changelog entry under `### Unreleased` in `changelog.md`
+  for the user-facing impact of this change.
+- [ ] No changelog entry is required because this PR is one of:
+  documentation-only, test-only, CI / build-only, or a pure internal refactor
+  with no observable customer impact.
+
+If the second box is checked, briefly justify here:
+
+>