epic-4/story-5: Deliver Advanced Documentation and Migration Guides by usmanabbas7 · Pull Request #42 · convertcom/python-sdk

usmanabbas7 · 2026-06-08T12:26:41Z

Story 4.5 — Deliver Advanced Documentation and Migration Guides

Part of sprint sprint/2026-04-06-convert-python-sdk. Stacked on epic-4/story-4 (#41 → #40 → #39 → #38 → epic-3 chain).

What was built

Ten topic/migration guides under docs/ (built as a genuine docs-heavy story against the repo docs/ tree — the story file's stale "moved to wiki / docs removed" Codex narrative was verified false against the live branch and ignored):

index.md, initialization.md, evaluation.md, tracking.md, queue-control.md (AC#1)
debugging.md (deferred into this story from 4-3 — documents the partial cross-SDK diagnostic surface: reason/environment/bucket_value/variation_key + hashed visitor, DiagnosticReason enum)
extending.md (deferred into this story from 4-4 — documents the hybrid injection contract: Core(config, *, transport=…), storage via config.data_store, @runtime_checkable ports/adapters)
support-workflows.md
migration-from-rest.md (AC#2), migration-from-javascript.md (AC#3)
README Documentation section cross-linking all guides

Anti-drift coverage

New tests/test_docs_samples.py + tests/docs_sample_config.py execute every code sample in every guide against the current public API (# doctest: run extraction harness), so docs cannot drift. The existing Story-1.6 tests/test_examples.py drift guard was left untouched.

Quality

Tests: 642 → 687 (+45 doc-sample tests). Zero regressions.
Readiness: PASS 9/10 round 1, 0 auto-delegations.
Code review: clean round 1 (no issues ≥75 confidence).
The drift guard caught 3 genuine API-accuracy issues during dev (Transport __enter__/__exit__, lifecycle (payload, error=None), offline flush() needs injected transport).

Scope notes

Closes documentation requirements FR54–FR57 (per F-054 correction; FR53/quickstart is Story 1.6).
Task 4.1 (docs-lint / dead-link CI step) is out of scope — handed off to Story 5.1's workflow (per F-024).
Beads: epic ai-driven-product-dev-nlwo; tasks -2tks, -o7au, -x758 — closed.

🤖 Generated with Claude Code

gemini-code-assist

Code Review

This pull request introduces a comprehensive set of advanced documentation guides under docs/ covering initialization, evaluation, tracking, queue control, debugging, extending, support workflows, and migrations. It also adds a shared sample configuration and a robust drift-protection test suite in tests/test_docs_samples.py to ensure that code snippets in the documentation remain valid and executable against the current public API. Feedback on the changes includes removing an unused helper function in the test suite, refining the __exit__ method signature in the extension guide's code sample, and using a more precise type hint for a helper function in the sample configuration.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-08T12:28:30Z

+def _all_python_fences(text: str) -> list[str]:
+    """Return the bodies of EVERY fenced python block (executable or not)."""
+    pattern = re.compile(r"```python[^\n]*\n(.*?)```", re.DOTALL)
+    return [m.group(1) for m in pattern.finditer(text)]
+


The function _all_python_fences is defined but never used anywhere in the test suite. To maintain a clean and maintainable codebase, it is recommended to remove this unused function.

References

PEP 8 recommends removing dead or unused code to keep the codebase clean and maintainable. ^(link)

gemini-code-assist · 2026-06-08T12:28:30Z

+    def __exit__(self, *exc):
+        self.close()
+        return False


The __exit__ method of a context manager should ideally follow the standard signature __exit__(self, exc_type, exc_val, exc_tb) instead of using *exc. This ensures better compatibility with static analysis tools, IDEs, and type checkers.

Suggested change

def __exit__(self, *exc):

self.close()

return False

def __exit__(self, exc_type, exc_val, exc_tb):

self.close()

return False

References

Standard Python context managers should implement the __exit__ method with the explicit (self, exc_type, exc_val, exc_tb) signature for clarity and tool compatibility. ^(link)

gemini-code-assist · 2026-06-08T12:28:31Z

+from typing import Any, Dict
+
+
+def _rule_country(value: str) -> dict:


The type hint dict is imprecise. Since Dict and Any are already imported from typing, using Dict[str, Any] provides better type safety and consistency with the rest of the file (e.g., SAMPLE_CONFIG: Dict[str, Any]).

Suggested change

def _rule_country(value: str) -> dict:

def _rule_country(value: str) -> Dict[str, Any]:

References

PEP 484 and PEP 8 encourage precise type hinting to improve code readability and static analysis. ^(link)

Beads: ai-driven-product-dev-2tks Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

index, initialization, evaluation, tracking, queue-control guides with executable doctest-run samples bound to the current public API. Beads: ai-driven-product-dev-2tks Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Beads: ai-driven-product-dev-o7au Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ation (GREEN) debugging (diagnose_* surface, closed DiagnosticReason, redaction-safe log seam), extending (runtime_checkable Transport/DataStore/EventBus seams, keyword-only transport injection, data_store field, no logger Protocol), support-workflows. Beads: ai-driven-product-dev-o7au Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Beads: ai-driven-product-dev-x758 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…entation (GREEN) migration-from-rest (endpoint mapping + batching/dedup/lifecycle/redaction callouts, runnable SDK-side flow), migration-from-javascript (concept map, deliberate Pythonic differences, parity evidence), README Documentation section linking docs/index.md + all guides. Beads: ai-driven-product-dev-x758 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

usmanabbas7 · 2026-06-15T12:02:09Z

F-066 propagation (rebase onto remediated 3-3)

Rebased onto the remediated stack. Does not modify evaluation/segments.py; latch fix inherited cleanly (byte-identical to remediated 3-3), no conflicts.

uv run pytest → 697 passed
CI gate: no .github/workflows/ on this branch → no-ci.

abbaseya · 2026-06-18T16:30:57Z

Superseded — all commits already in main (bc76b64). Closing without merge as part of post-sprint cleanup.

usmanabbas7 self-assigned this Jun 8, 2026

usmanabbas7 requested a review from clllaur June 8, 2026 12:26

gemini-code-assist Bot reviewed Jun 8, 2026

View reviewed changes

usmanabbas7 mentioned this pull request Jun 8, 2026

epic-5/story-1: Establish Maintainer Release and Parity Validation Workflow #43

Closed

usmanabbas7 force-pushed the epic-4/story-4-support-integration-customization-and-extension-boundaries branch from ec7ed31 to 1338c8c Compare June 14, 2026 17:09

usmanabbas7 force-pushed the epic-4/story-5-deliver-advanced-documentation-and-migration-guides branch from 65e82a8 to 16fccf1 Compare June 14, 2026 17:09

usmanabbas7 force-pushed the epic-4/story-4-support-integration-customization-and-extension-boundaries branch from 1338c8c to 31b611a Compare June 15, 2026 11:30

usmanabbas7 and others added 6 commits June 15, 2026 16:31

wf(wf-45docs): [DOC-1] Core topic guides — tests (RED)

ef03b45

Beads: ai-driven-product-dev-2tks Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(wf-45docs): [DOC-2] debugging/extending/support guides — tests (RED)

839f718

Beads: ai-driven-product-dev-o7au Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(wf-45docs): [DOC-3] migration guides + README links — tests (RED)

e5af5c4

Beads: ai-driven-product-dev-x758 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

usmanabbas7 force-pushed the epic-4/story-5-deliver-advanced-documentation-and-migration-guides branch from 16fccf1 to cc3c404 Compare June 15, 2026 11:31

abbaseya closed this Jun 18, 2026

abbaseya deleted the epic-4/story-5-deliver-advanced-documentation-and-migration-guides branch June 18, 2026 16:31

Navigation Menu

Uh oh!

epic-4/story-5: Deliver Advanced Documentation and Migration Guides - #42

epic-4/story-5: Deliver Advanced Documentation and Migration Guides#42
usmanabbas7 wants to merge 6 commits into
epic-4/story-4-support-integration-customization-and-extension-boundariesfrom
epic-4/story-5-deliver-advanced-documentation-and-migration-guides

usmanabbas7 commented Jun 8, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

usmanabbas7 commented Jun 15, 2026

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		from typing import Any, Dict


		def _rule_country(value: str) -> dict:

	def _rule_country(value: str) -> dict:
	def _rule_country(value: str) -> Dict[str, Any]:

Uh oh!

Conversation

usmanabbas7 commented Jun 8, 2026

Story 4.5 — Deliver Advanced Documentation and Migration Guides

What was built

Anti-drift coverage

Quality

Scope notes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

usmanabbas7 commented Jun 15, 2026

F-066 propagation (rebase onto remediated 3-3)

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants