Release: Adds versions 3.60.0 and 3.61.0-preview.0#5876
Conversation
- Updates ClientOfficialVersion to 3.60.0 - Updates ClientPreviewVersion to 3.61.0 - Updates ClientPreviewSuffixVersion to preview.0 - Adds changelog entries for 3.60.0 and 3.61.0-preview.0 - Adds API contract files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ananth7592
requested review from
FabianMeiswinkel,
Pilchie,
jeet1995,
kirankumarkolli,
kundadebdatta,
kushagraThapar,
sboshra and
xinlian12
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
ananth7592
changed the title
kundadebdatta
left a comment
kundadebdatta
left a comment
There was a problem hiding this comment.
LGTM. Left one minor comment.
kushagraThapar
left a comment
kushagraThapar
left a comment
There was a problem hiding this comment.
👋 Courtesy deep review of this release PR. This is not a blocking or requesting-changes review — just a thorough pass through the changelog accuracy, version bumps, contract snapshots, and release-PR hygiene, posted as a comment so you can take or leave individual items per your judgment. The blockers/majors are the high-signal items; minors and forward-pointers are nice-to-haves.
TL;DR:
- Version bumps in
Directory.Build.propsand contract filenames are all correct ✅. - The empty
### Unreleasedper-PR scaffold from #5864 was preserved correctly ✅. - Two real changelog-accuracy issues worth fixing before tagging: (a)
[5804]and[5783]reference SemanticRerank surface that is preview-only, so listing them in the3.60.0GA section may mislead customers; (b) at least 5 customer-facing PRs merged between 2026-04-25 and 2026-05-18 are missing from the GA changelog, including a .NET 10 LINQ-breakage fix.
Pre-flight verification gate: every "missing X / diverges from convention" claim below includes a verified_by_grep line with the actual command + output, so you don't need to re-derive any of the evidence.
🔴 Worth fixing before tagging (3)
1. [5804] and [5783] listed in 3.60.0 GA but reference preview-only SemanticRerank surface
File: changelog.md — 3.60.0 section (Features Added + Bugs Fixed)
The new 3.60.0 GA section lists:
[5804] SemanticReranking: Adds Configurable Request Timeout[5783] Container: Fixes SemanticRerankAsync TypeLoadException in derived classes
But Container.SemanticRerankAsync, SemanticRerankResult, RerankScore, InferenceRequestTimeout, WithInferenceRequestTimeout, etc. are not in API_3.60.0.txt — they only appear in API_3.61.0-preview.0.txt. The parent SemanticRerank API was added in #5445 / 3.57.0-preview.0 and has never been promoted to GA. Both #5804 and #5783 already shipped in the existing 3.60.0-preview.0 section, so this looks like a copy-paste rather than a deliberate GA promotion.
Verification:
$ grep -i "semantic\|rerank\|InferenceRequestTimeout" API_3.60.0.txt
(no matches)
$ grep -n "SemanticRerank\|InferenceRequestTimeout" API_3.61.0-preview.0.txt
312: public virtual Task<SemanticRerankResult> SemanticRerankAsync(...)
417: public TimeSpan InferenceRequestTimeout { get; set; }
1236: public class SemanticRerankResult
1538: public CosmosClientBuilder WithInferenceRequestTimeout(...)
Why it matters: GA changelog readers will conclude SemanticRerankAsync is now generally available and assume the GA NuGet package exposes it. They will hit TypeLoadException / "method not found" at runtime because the GA assembly does not contain the type.
Suggested fix: Could you please move [5804] and [5783] out of the ### 3.60.0 section? Since both reference SemanticRerank surface that is preview-only (verified — no matches in API_3.60.0.txt), they can stay only in the existing ### 3.60.0-preview.0 section where they already shipped. This matches how prior release PR #5810 placed them.
2. Missing changelog entry: [5819] .NET 10 MemoryExtensions.Contains LINQ breaking-change fix
File: changelog.md — 3.60.0 Bugs Fixed
PR #5819 (Linq: Fixes .NET 10 MemoryExtensions.Contains breaking change in LINQ queries, labels QUERY auto-merge, merged 2026-05-04, fixes issue #5518) is not listed.
Verification:
$ gh pr view 5819 --repo Azure/azure-cosmos-dotnet-v3 --json title,labels,mergedAt
{"title":"Linq: Fixes .NET 10 MemoryExtensions.Contains breaking change in LINQ queries",
"labels":[{"name":"QUERY"},{"name":"auto-merge"}],
"mergedAt":"2026-05-04T17:29:12Z"}
Why it matters: .NET 10 (C# 14) changed array.Contains(x) to use MemoryExtensions.Contains with ReadOnlySpan<T> instead of Enumerable.Contains, which breaks the LINQ-to-SQL translator. Customers upgrading to .NET 10 will get silently broken LINQ queries (wrong results or runtime exceptions). This is exactly the kind of fix the GA changelog exists to advertise.
Suggested fix: Could you please add - [5819] LINQ: Fixes .NET 10 MemoryExtensions.Contains breaking change in LINQ queries to the 3.60.0 Bugs Fixed section? Merged on May 4, well before the May 18 release cut.
3. Missing changelog entry: [5823] PPAF LocationCache read fallback fix
File: changelog.md — 3.60.0 Bugs Fixed
PR #5823 (LocationCache: Fixes read fallback to use WriteEndpoints[0] when PPAF enabled and all regions excluded, merged 2026-05-04) is missing.
Verification:
$ gh pr view 5823 --repo Azure/azure-cosmos-dotnet-v3 --json title,mergedAt
{"title":"LocationCache: Fixes read fallback to use WriteEndpoints[0] when PPAF enabled and all regions excluded",
"mergedAt":"2026-05-04T19:37:42Z"}
Why it matters: This is a PPAF correctness fix — reads were routed to the wrong endpoint when all read regions were excluded. Customers operating with EnablePartitionLevelFailover = true need to know 3.60.0 ships the fallback fix, especially anyone diagnosing regional-outage behavior.
Suggested fix: Could you please add - [5823] LocationCache: Fixes read fallback to use WriteEndpoints[0] when PPAF enabled and all regions excluded to the 3.60.0 Bugs Fixed section?
🟡 Strongly recommend (4)
4. Missing changelog entry: [5816] HttpTimeoutPolicy aggressive 500ms first-attempt timeout fix
File: changelog.md — 3.60.0 Bugs Fixed
PR #5816 (HttpTimeoutPolicy: Fixes aggressive 500ms first-attempt timeout in HttpTimeoutPolicyControlPlaneRetriableHotPath, merged 2026-05-06) is missing.
Verification:
$ gh pr view 5816 --repo Azure/azure-cosmos-dotnet-v3 --json title,mergedAt
{"title":"HttpTimeoutPolicy: Fixes aggressive 500ms first-attempt timeout in HttpTimeoutPolicyControlPlaneRetriableHotPath",
"mergedAt":"2026-05-06T17:41:32Z"}
Suggested fix: Could you please add - [5816] HttpTimeoutPolicy: Fixes aggressive 500ms first-attempt timeout in HttpTimeoutPolicyControlPlaneRetriableHotPath to the 3.60.0 Bugs Fixed section? Customers on slow networks (cross-region, mobile, cold-start scenarios) regularly hit the 500ms first-attempt timeout — exactly the kind of fix a customer searching the changelog for "timeout" / "latency" would expect to find.
5. Missing changelog entry: [5618] Diagnostics null contacted-region name for multimaster hub fallback
File: changelog.md — 3.60.0 Bugs Fixed
PR #5618 (Diagnostics: Fixes null contacted region name for multimaster hub fallback (410/21005), merged 2026-05-05, closes issue #5095) is missing.
Verification:
$ gh pr view 5618 --repo Azure/azure-cosmos-dotnet-v3 --json title,mergedAt
{"title":"Diagnostics: Fixes null contacted region name for multimaster hub fallback (410/21005)",
"mergedAt":"2026-05-05T18:44:26Z"}
Suggested fix: Could you please add - [5618] Diagnostics: Fixes null contacted region name for multimaster hub fallback (410/21005). Closes #5095. to the 3.60.0 Bugs Fixed section? Diagnostics output is a contract that customers parse for telemetry pipelines (Geneva / GCS / App Insights), and the issue reporter for #5095 deserves a clear "shipped in 3.60.0" signal.
6. Missing Direct package version bump entry ([5839] for 3.43.0; also a separate bump to 3.43.1)
File: changelog.md — 3.60.0 Features Added or Other Changes
PR #5839 ([Direct package version update]: Adds direct package version 3.43.0, merged 2026-05-06) is not in the changelog, and DirectVersion on main is 3.43.1 (so an additional bump beyond #5839 has landed too, which I could not locate via PR title search — it may have been an internal pipeline change). The 3.59.0 GA release set the precedent of listing Direct bumps under Features Added ([5779] Direct: Adds Direct package version bump to 3.42.4).
Verification:
$ gh pr view 5839 --repo Azure/azure-cosmos-dotnet-v3 --json title,mergedAt
{"title":"[Direct package version update]: Adds direct package version 3.43.0",
"mergedAt":"2026-05-06T02:52:44Z"}
$ grep -n "DirectVersion" pr-5876.diff
6: <DirectVersion>3.43.1</DirectVersion> # already 3.43.1 on main, untouched by this PR
$ grep "5779\|Direct" changelog-main.md | head -3
- [5779] Direct: Adds Direct package version bump to 3.42.4 # prior precedent in 3.59.0
Suggested fix: Could you please add - [5839] Direct: Adds Direct package version bump to 3.43.0 (and a separate entry for the 3.43.1 bump if it was a different PR) under 3.60.0? I am curious to learn whether 3.43.1 was a hotfix bump on top of 3.43.0 — if so, surfacing both PRs and what 3.43.1 brings would help customers tracking Direct-mode fixes.
7. 3.60.0 GA section diverges from the delta-only convention used in 3.58.0 / 3.59.0 GA
File: changelog.md — 3.60.0 vs 3.60.0-preview.0
The convention from 3.58.0 and 3.59.0 GA: each release section is a delta of items merged into main between the prior section's release date and this section's release date. By that convention:
3.60.0-preview.0(2026-04-24) listed deltas from3.59.0-preview.0(2026-03-19).3.60.0GA (2026-05-18) should list deltas from3.60.0-preview.0(2026-04-24), not re-list items already in the prior preview.3.61.0-preview.0(2026-05-18) should list preview-only deltas since3.60.0-preview.0— which this PR does correctly (#5815,#5848). 👍
This PR's 3.60.0 GA section currently duplicates 4 of its 5 entries from the prior 3.60.0-preview.0 section (#5804, #5783, and both #5825 entries appear in both sections). After moving #5804 and #5783 out per finding 1, please also consider whether the #5825 entries belong in both sections or only in the GA section — the AllVersionsAndDeletes GA promotion is uniquely a GA event, so it belongs in 3.60.0 GA; the CFP StartTime exemption is a behavioral fix that already shipped in the preview, so by delta-only convention it could be left only in the preview section.
Verification:
$ sed -n '/<a name="3.59.0"\/>/,/<a name="3.59.0-preview.0"\/>/p' changelog-main.md | grep "^- \["
- [5579] Change Feed Processor: Adds Lease container export support
- [5709] Performance: ... AAD authorization signature
- [5731] DNS dot-suffix: ...
- [5755] Exceptionless: ... 400 status code
- [5756] Exceptionless: ... 404/1002 status code
- [5757] Exceptionless: ... 403
- [5779] Direct: ... 3.42.4
- [5786] Region Availability: ... from Direct 3.42.4
- [5788] Socket Handler: HTTP/2 PING keep-alive
- [5553] NativeDLLs: ...
- [5588] LINQ: ... memory leak ...
- [5617] ChangeFeedProcessor: first-change skip ...
- [5636] CosmosClientBuilder: self-referencing loop ...
- [5748] Routing: GetOverlappingRanges CPU overhead ...
- [5807] ChangeFeedProcessor: lease de-duplication ...
- [5778] DocumentClient: Potential Memory Leak ...
# 3.59.0 GA lists items NOT in 3.59.0-preview.0 — delta-only convention.
Suggested fix: Could you please align this release with the delta-only convention used in 3.58.0 and 3.59.0 GA? At minimum, after fixing finding 1 (SemanticRerank misclassification), please also confirm whether the #5825 entries should appear in both sections or only in the GA section. As an alternative to stripping duplicates, light copy-edits like "(originally shipped in 3.60.0-preview.0)" would also help readers track lineage.
Architecturally, would the team consider mechanizing this? A CI check at release-PR-open time that diffs gh pr list --state merged --search "merged:>=<last-release-date>" against the PR numbers cited in the new changelog section would have caught findings 2, 3, 4, 5, 6 immediately and would prevent future backfills like PR #5860.
🟢 Minor (3)
8. PR title + description hygiene
- PR title "Release: Adds version 3.60.0" omits the
3.61.0-preview.0also being shipped. (Prior release PR #5810 had the same gap, so this is pre-existing.) - PR description Type-of-change checkboxes (
[]) and Changelog checkboxes ([ ]) are all unchecked. Compared with prior release PR #5810, this PR's description is also missing the inline GA / Preview API contract diffs and the explicit GA-vs-Preview changelog split that made #5810 much easier to review.
Suggested fix: Could you please consider (1) updating the title to "Release: Adds versions 3.60.0 and 3.61.0-preview.0", (2) ticking the appropriate Type-of-change and Changelog boxes, and (3) porting over the inline API-contract-diff and split-changelog format from PR #5810? It would speed up future reviewer verification significantly.
9. New contract .txt files use CRLF; all 175 pre-existing contract files use LF
Files: Microsoft.Azure.Cosmos/contracts/API_3.60.0.txt + API_3.61.0-preview.0.txt
Verification:
$ for f in API_3.60.0-PR-HEAD.txt API_3.61.0-preview.0-PR-HEAD.txt API_3.60.0-preview.0-main.txt API_3.59.0-main.txt; do
cr=$(tr -cd '\r' < $f | wc -c)
lf=$(tr -cd '\n' < $f | wc -c)
echo "$f: CR=$cr LF=$lf"
done
API_3.60.0-PR-HEAD.txt: CR=1816 LF=1816 # CRLF
API_3.61.0-preview.0-PR-HEAD.txt: CR=1968 LF=1968 # CRLF
API_3.60.0-preview.0-main.txt: CR=0 LF=1948 # LF only
API_3.59.0-main.txt: CR=0 LF=1778 # LF only
The contracts directory has been LF-only for the entire history of the SDK (175/175 pre-existing files). Mixing CRLF in two new files produces noisy whitespace diffs on every subsequent contract regeneration touched on macOS/Linux, can confuse line-count tools, and may trip "is this a real change?" judgment on future API-surface PRs. There's no .gitattributes to auto-normalize.
Suggested fix: Could you please regenerate the two new .txt files with LF line endings (e.g., dos2unix Microsoft.Azure.Cosmos/contracts/API_3.60.0.txt Microsoft.Azure.Cosmos/contracts/API_3.61.0-preview.0.txt and re-commit) so they match the rest of the contracts directory? As a follow-up, would you consider adding *.txt text eol=lf to a new Microsoft.Azure.Cosmos/contracts/.gitattributes so the next release author on Windows doesn't hit this?
10. PR #5848 title prefix [Internal] is misleading
PR #5848 is titled [Internal] VectorEmbeddingPolicy: Adds EmbeddingSource block to Embedding model, but API_3.61.0-preview.0.txt confirms it adds public customer-facing surface (public sealed class EmbeddingSource : IEquatable<EmbeddingSource> + EmbeddingSource Embedding.EmbeddingSource { get; set; }). The changelog entry here correctly classifies it as a customer-facing feature — just the upstream PR title that's misleading.
Verification:
$ grep -n "EmbeddingSource" API_3.61.0-preview.0.txt
... public EmbeddingSource EmbeddingSource { get; set; }
... public bool Equals(EmbeddingSource that);
... public EmbeddingSource();
... public sealed class EmbeddingSource : IEquatable<EmbeddingSource>
Suggested fix: No change needed in this release PR. For the next reviewer-tooling iteration, could the team consider clarifying when [Internal] is and isn't appropriate (e.g., "only for changes with no observable public surface")? Any automated classifier using the [Internal] prefix as a heuristic for "no customer impact / skip changelog" would have incorrectly skipped this entry.
💬 Process notes (2)
11. PR #5875 merged same day as release — confirm inclusion
PR #5875 (Query: Adds new QueryFeature and QueryInfo fields for embedding parameters, labels QUERY auto-merge) merged 2026-05-18T18:07:02Z — the same day as this release PR. Depending on whether the release branch was cut before or after #5875 merged, the change is either in the GA build or not.
Suggested fix: Could you please confirm whether the release branch users/amudumba_microsoft/release-3.60.0 was cut before or after PR #5875 merged? If after, please add - [5875] Query: Adds new QueryFeature and QueryInfo fields for embedding parameters; if before, no action — the change will ship in 3.61.0 / 3.62.0-preview.0. Either way, mentioning the cut-off SHA in the PR description would help future reviewers.
12. Empty ### Unreleased scaffold correctly preserved (positive observation)
The empty ### Unreleased H3 with four H4 subheadings (Features Added / Breaking Changes / Bugs Fixed / Other Changes) is preserved. This matches the per-PR Unreleased workflow from PR #5864. The <a name="unreleased"/> anchor was NOT renamed to a version-specific anchor (which #5864 flagged as a trade-off the author chose to accept). No action — just confirming the workflow held up on first contact. 👍
🧭 Forward-pointers to upstream PRs (NOT blocking this release)
These two items are agentic-readiness findings against surface that is being snapshotted in API_3.61.0-preview.0.txt, not introduced by THIS PR. Surfacing them as forward-pointers so the next reviewer of a Semantic Rerank PR can raise them before the surface promotes to GA:
F1 — Container.SemanticRerankAsync uses untyped IDictionary<string, object> options bag
$ grep -n SemanticRerankAsync API_3.61.0-preview.0.txt
308: public virtual Task<SemanticRerankResult> SemanticRerankAsync(string rerankContext,
IEnumerable<string> documents,
IDictionary<string, object> options=null,
CancellationToken cancellationToken=...);
Opaque to LLM tool-callers — they can't introspect option keys or value types from the method signature alone. Idiomatic Cosmos .NET surfaces use typed records (e.g., QueryRequestOptions, ItemRequestOptions). Cheaper to fix in preview than after GA freezes the shape.
F2 — SemanticRerankResult exposes Latency and TokenUseage as Dictionary<string, object> (+ TokenUseage looks like a typo of TokenUsage)
1233: public class SemanticRerankResult
1234: {
1235: public HttpResponseHeaders Headers { get; }
1236: public Dictionary<string, object> Latency { get; }
1237: public IReadOnlyList<RerankScore> RerankScores { get; }
1238: public Dictionary<string, object> TokenUseage { get; } // ← typo?
Renaming a public field after GA is much more expensive than fixing it now in preview. Could you please help me understand whether TokenUseage is intentional or a typo of TokenUsage, and whether typed records for Latency / TokenUsage are planned before the preview surface promotes to GA?
✅ What was explicitly checked and is fine (rigor receipts)
Surfacing the verified-negatives so the work is visible and you don't have to wonder what was looked at:
- Version bump arithmetic — verified-OK.
ClientOfficialVersion 3.59.0 → 3.60.0,ClientPreviewVersion 3.60.0 → 3.61.0, suffixpreview.0unchanged. Matches convention across prior releases. - API contract filename / version stamp — verified-OK. Filenames match the version strings.
Unreleasedscaffold drop or rename — verified-negative. PR #5864 flagged that renaming<a name="unreleased"/>each release breaks external links; this PR did NOT rename — anchor remains on a stable heading.- New public surface added in this PR itself — verified-negative. The
API_*.txtfiles are snapshots of previously merged PRs (#5804, #5815, #5825, #5848, #5870), not new surface introduced here. Agentic findings (F1, F2 above) route to originating PRs, not to this release PR. - Date format inconsistency — verified-negative. New dates
2026-5-18(no leading zeros) match established file-wide format. - Anchor naming inconsistency — verified-negative.
<a name="3.60.0"/>and<a name="3.61.0-preview.0"/>match the existing pattern. - Empty
### Breaking Changes/### Other Changessubsections missing from new release sections — verified-negative. Historical convention (3.59.0, 3.58.0, 3.57.0) omits empty subsection headings from RELEASED sections; only theUnreleasedsection keeps all four. The new entries (Features Added + Bugs Fixed only for 3.60.0; Features Added only for 3.61.0-preview.0) follow this convention. - Missing tests / missing benchmarks — verified-negative (N/A). The PR contains zero source-code changes (only
Directory.Build.props, two contract.txtfiles,changelog.md); no source surface changed → no test/benchmark-coverage probe applies. - Diverges from peer SDK — verified-negative (N/A). Release PRs are SDK-internal (version manifest + per-SDK contract format); cross-SDK parity is not applicable.
Suggested ordering for the author
- Worth fixing before tagging (3): findings 1, 2, 3.
- Strongly recommend (4): findings 4, 5, 6, 7.
- Nice-to-have (3): findings 8, 9, 10.
- Confirm with author: finding 11 (#5875 same-day merge inclusion).
- Forward-pointers for the next SemanticRerank PR reviewer: F1, F2 (not for this PR's author).
Thanks for shipping this! Let me know if any of the findings need more context — happy to dig further.
ananth7592
changed the title
Addresses review feedback from kushagraThapar: - Adds [5819] .NET 10 LINQ MemoryExtensions.Contains fix - Adds [5816] HttpTimeoutPolicy 500ms first-attempt timeout fix - Adds [5618] Diagnostics null contacted-region name fix - Adds [5823] LocationCache PPAF read fallback fix - Adds [5839] Direct package version bump to 3.43.0 - Converts API_3.60.0.txt and API_3.61.0-preview.0.txt from CRLF to LF Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ananth7592
dismissed stale reviews from kundadebdatta and NaluTripician
via
3929895
|
Thanks @kushagraThapar for the thorough review! Here's how each item has been addressed: ✅ Fixed1. [5804] and [5783] SemanticRerank in GA section — Moved both to 3.61.0-preview.0 only. ✓ 2. Missing [5819] .NET 10 LINQ fix — Added to 3.60.0 Bugs Fixed. ✓ 3. Missing [5823] PPAF LocationCache fix — Added to 3.60.0 Bugs Fixed. ✓ 4. Missing [5816] HttpTimeoutPolicy fix — Added to 3.60.0 Bugs Fixed. ✓ 5. Missing [5618] Diagnostics null region name — Added to 3.60.0 Bugs Fixed. ✓ 6. Missing Direct version bump [5839] — Added 8. PR title — Updated to 9. CRLF → LF in contract files — Converted both 📝 Acknowledged (no code change needed)7. Delta-only convention for #5825 — The two #5825 entries in 3.60.0 GA represent the actual GA promotion event (AllVersionsAndDeletes was preview-only before 3.60.0). The Feature entry records the promotion, and the Bugs Fixed entry records a behavioral change that only applies once AVAD is GA (StartTime back-off exemption). This follows the same pattern as 3.59.0 which lists items that are uniquely relevant to the GA surface. Since both entries describe GA-specific behavior, keeping them in the GA section is intentional. 10. PR #5848 [Internal] prefix misleading — Agreed this is a pre-existing title issue on the upstream PR. No change needed in this release PR. Good callout for future tooling. 11. PR #5875 same-day merge — Confirmed: the release branch was cut before #5875 merged. The branch base is 12. Unreleased scaffold preserved — 👍 F1/F2. SemanticRerank forward-pointers — Noted for next SemanticRerank PR review. Not actionable on this release PR. |
kushagraThapar
left a comment
kushagraThapar
left a comment
There was a problem hiding this comment.
LGTM, thanks @ananth7592!
4 participants
Pull Request Template
Description
Following are the contract differences
GA 3.59.0 ==> 3.60.0
Preview 3.60-preview.0.txt ==> 3.61-preview.0.txt
Type of change
Please delete options that are not relevant.
Closing issues
To automatically close an issue: closes #IssueNumber
Changelog
### Unreleasedinchangelog.mdfor the user-facing impact of this change.
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: