release: 3.0.0 — public-API rename release (#348, #349, #351)

[TexasCoding]

v3.0.0 — First major release in the v3 line

Three breaking-rename issues (#348, #349, #351) deferred from the v2.7.0 audit closure now land with one-release deprecation aliases. Wire protocol unchanged from v2.7.0; v3 is purely a Python-API ergonomics break.

Pipeline

Single wave (W4) of the Round-3 audit closure plan. 2 parallel PRs in disjoint worktrees:

PR	Issues	Theme
#377 (W4-A)	#348, #349	CommunicationsResource sub-namespaces + list_all_<noun> standardization
#376 (W4-C)	#351	fills relocation orders → portfolio

Each ran through the claude-code-review bot loop (2 rounds each) before squash-merge.

Breaking changes

All three ship with @typing_extensions.deprecated aliases on old names — existing v2.x callers continue to work but get DeprecationWarning on every call. Aliases removed no sooner than v3.1.0.

1. CommunicationsResource sub-namespaces (#348)

# v2.x (deprecated in v3.0.0)
client.communications.list_rfqs(...)
client.communications.create_rfq(...)
client.communications.accept_quote(quote_id, accepted_side="yes")

# v3.0.0+
client.communications.rfqs.list(...)
client.communications.rfqs.create(...)
client.communications.quotes.accept(quote_id, accepted_side="yes")

12 forwarders total split across rfqs and quotes sub-resources. The misc client.communications.get_id(...) stays at the top level. New sub-resource classes (RFQsResource, QuotesResource, async variants) exported from kalshi/__init__.py.

2. *_all naming standardization (#349)

# v2.x (deprecated in v3.0.0)
for trade in client.markets.list_trades_all(ticker="..."):
    ...

# v3.0.0+
for trade in client.markets.list_all_trades(ticker="..."):
    ...

3. fills relocation: orders → portfolio (#351)

# v2.x (deprecated in v3.0.0)
page = client.orders.fills(ticker="...")

# v3.0.0+
page = client.portfolio.fills(ticker="...")

What's in this commit

• CHANGELOG.md — full 3.0.0 entry with BEFORE/AFTER snippets for each rename
• docs/migration.md — v2.7 → v3.0 section added at the top
• docs/migrations/v2-to-v3.md — new dedicated migration guide with search-and-replace cheat sheet
• ROADMAP.md — v3.0.0 shipped entry
• mkdocs.yml — Migration nav expanded with v2 → v3 sub-entry
• pyproject.toml — version bump 2.7.0 → 3.0.0
• AGENTS.md + CLAUDE.md — gitnexus stats refreshed (8568 symbols, 17351 relationships, 300 flows)

Verification

• uv run ruff check kalshi/ tests/ docs/ — clean
• uv run mypy kalshi/ — clean (76 source files, --strict)
• uv run pytest tests/ — 2954 passed, 258 skipped (69 expected DeprecationWarnings from alias coverage tests)

Removal schedule

The v3.0.0 deprecation aliases will be removed no sooner than v3.1.0. Each deprecated method uses @typing_extensions.deprecated (PEP 702) so type checkers and IDEs surface the warning at the call site.

[claude]

Code Review — PR #378: release: 3.0.0

Overview

This is a release-coordination PR — it bumps the version, adds the changelog entry, migration docs, and roadmap update. The actual implementation (deprecation aliases, sub-namespaces, fills relocation) landed in #377 and #376 before this was opened. The diff is therefore entirely documentation and metadata, which makes it straightforward to review.

---

✅ What's done well

• Migration guide (docs/migrations/v2-to-v3.md) is excellent: search-and-replace cheat sheet, before/after code blocks for each rename, async API parity note, type-annotation imports, pytest filterwarnings tip for enforcing migration during testing, and a rationale section for the major version bump. This is genuinely user-friendly.
• CHANGELOG entry follows the established format — BEFORE/AFTER snippets, issue links, internal section, deprecation removal schedule. Consistent with prior entries.
• mkdocs.yml navigation correctly nests migrations/v2-to-v3.md under migration.md as a sub-entry.
• @typing_extensions.deprecated (PEP 702) is the right tool — surfaces at IDE/type-checker level, not just runtime. Good choice over a raw warnings.warn.

---

⚠️ Issues / things to verify

1. Date pre-dating in CHANGELOG and ROADMAP

CHANGELOG.md and ROADMAP.md both record the release date as 2026-05-23, but today is 2026-05-22. If this PR merges today, those dates will be wrong by one day. Minor, but changelog dates should match the actual merge/release date. Consider updating to 2026-05-22 before merge, or merging tomorrow.

2. GitNexus relationship count decreased

Before: 8490 symbols, 17402 relationships
After:  8568 symbols, 17351 relationships  (−51 relationships)

Adding four new resource classes (RFQsResource, QuotesResource, and async variants) plus their methods should increase relationships, not decrease them. This is likely just an index refresh artifact, but worth a quick npx gitnexus analyze before merging to confirm the index is current.

3. One-release deprecation window for a major-version break

The "no sooner than v3.1.0" window is tight for a semver major bump — users who pin to ^2.x will get this on upgrade and have only one release to migrate. This is consistent with the stated project policy, but might be worth documenting an estimated timeline for v3.1.0 (e.g., "expected ~4 weeks after v3.0.0") so users know how long they actually have.

4. docs/migrations/ directory — mkdocs serve sanity check

The new directory is new; confirm mkdocs build / mkdocs serve resolves it without a broken nav warning. (The path in mkdocs.yml is migrations/v2-to-v3.md, relative to the docs/ root — looks correct, just worth a quick local build.)

---

🔍 Nits

• docs/migration.md table: the third row under "Communications sub-namespaces" ((12 forwarders total...)) breaks the visual alignment slightly. Could merge that note into a table footer or a sentence below the table instead of a standalone row with empty "Old" and "New" cells — the current rendering may look odd depending on the markdown parser.
• ROADMAP entry is a single dense paragraph. Acceptable, but the bulleted format used by v2.7.0 below it is easier to scan.

---

Summary

The documentation is thorough and the release structure is sound. Two action items before merging:

1. Resolve the 2026-05-23 vs 2026-05-22 date in CHANGELOG and ROADMAP.
2. Run npx gitnexus analyze to explain the relationship-count drop and confirm the index is current.

The migration guide in particular is well above average — clear, actionable, and covers the deprecation detection tip that most guides omit. 👍

[TexasCoding]

Round-2 review addressed: corrected v3.0.0 release date in CHANGELOG and ROADMAP from 2026-05-23 to 2026-05-22 (the actual release date). Deferring: gitnexus relationship count delta (-51) is an indexing artifact from this run's scope-extraction warnings on test files; the 8568 symbol count correctly reflects the new sub-resource classes added. Deprecation window timeline note will be added when v3.1.0 lands.

[claude]

Code Review — PR #378: release: 3.0.0

Overall: This is a clean release-packaging PR. The actual code changes (deprecation aliases, sub-namespaces, fills relocation) already landed in #376 and #377 and are verifiable in the working tree. Review here focuses on the docs/metadata changes in scope.

---

Bug (should fix before merge)

kalshi/__init__.py:354 — __version__ is stale

# kalshi/__init__.py line 354 — currently
__version__ = "2.6.0"

The version hardcoded in __init__.py was not updated for v2.7.0, and this PR bumps pyproject.toml to 3.0.0 without touching __init__.py. Any caller doing import kalshi; kalshi.__version__ will see "2.6.0" instead of "3.0.0". Fix: update the hardcoded string to "3.0.0", or better yet, switch to the standard importlib.metadata pattern to eliminate future drift:

from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("kalshi-sdk")
except PackageNotFoundError:
    __version__ = "unknown"

---

Nit (minor, worth fixing)

Regex inconsistency in docs/migrations/v2-to-v3.md

The two filterwarnings examples use different regex patterns for the module selector:

# TOML example — line 138
"error::DeprecationWarning:kalshi.*"   # '.' matches any char, not literal dot

# Python example — line 148
module=r"kalshi(\..*)?"   # correct: escapes the literal dot

The TOML example's kalshi.* would technically also match kalshiXfoo (since . in pytest's regex is any character). Use kalshi(\..*)? for precision and to match the Python example directly:

filterwarnings = [
    "error::DeprecationWarning:kalshi(\\..*)?",
]

---

Observations (no action needed)

• CHANGELOG entry is thorough and well-structured — BEFORE/AFTER snippets, internal/polish split, and the explicit removal schedule are all good.
• Migration guide (docs/migrations/v2-to-v3.md) is excellent. The search-and-replace cheat sheet is immediately actionable, and the "Detecting deprecated calls" section with filterwarnings = ["error::..."] is a nice touch for teams running automated migrations.
• ROADMAP.md ordering — The v3.0.0 entry lands above the "See CHANGELOG.md..." separator line, which slightly breaks the visual grouping of that section. Not blocking, just worth noting for future releases.
• Deprecation approach — The @typing_extensions.deprecated + one-release alias window is a solid pattern. The aliases are confirmed present in the working tree (orders.py:566, markets.py:389, communications.py:614, etc.).
• mkdocs.yml nav expansion — Clean; the v2 → v3 sub-entry under Migration is the right structure.

---

Verdict: Block on the __version__ fix. The regex nit is worth cleaning up while you're in the doc. Everything else is ship-ready.