Docs/migration 1x to 2x

[ayushiahjolia]

Issue #, if available: N/A

Description of changes:
Migration guide for python v2

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Claude AI review

This PR adds a 1.x→2.x migration guide (docs/migration-1.x-to-2.x.md) and expands the WaitForConditionConfig docstring in waits.py. It is documentation-only.

I verified every concrete technical claim in the guide against the base-branch (2.x) source, since a migration guide's correctness is its whole value:

• Error hierarchy and package-root exports (DurableOperationError, StepError/InvokeError/ChildContextError/WaitForConditionError, graded CallbackError subtypes, SerDesError as a direct child of DurableExecutionsError, RetryableSerDesError as a retryable InvocationError) — match exceptions.py/__init__.py.
• error_type semantics and the reconstructed-__cause__ behavior — match ErrorObject.raise_as_operation_error and the graded callback error construction in context.py.
• throw_if_error() raising ChildContextError/SerDesError/BatchCompletionError, plus the DurableOperationError-vs-SerDesError catch guidance — match concurrency/models.py.
• First-run serialize→deserialize round-trip for step, child context, map/parallel, and wait_for_condition (incl. initial_state) — confirmed in step.py, child.py, wait_for_condition.py.
• wait_for_callback returning the payload directly and its callback-error translation, and using the default serdes for the enclosing child context — match context.py/callback.py.
• Removed names, construction-time validation rules (max_concurrency/min_successful >= 1, should_complete mutual exclusion, deferred min_successful > total), all_completed(), the "summary" envelope key, and the required attempt field on StepContext/WaitForConditionCheckContext — all confirmed in config.py/types.py/context.py.

Example imports are correct (e.g. CompletionConfig from .config, which is not re-exported at the root). The waits.py docstring accurately describes the round-trip and default-serdes behavior.

No actionable correctness, determinism, API-compatibility, or typing issues were found in the diff.

Residual notes (non-blocking): docs-only change, so no tests are required under the repo policy; the new guide is not linked from any index in the diff, and the PR is still marked draft — neither is a defect in the changed lines.

Reviewed commit 6f1d145c148c5b2064f1c0e3c18e38af84ba2305. Workflow run

[github-actions]

Codex AI review

[P1] Document that the default map configuration is affected too. context.map(..., config=None) constructs MapConfig(), whose all-None CompletionConfig is treated as fail-fast in 2.x. Callers relying on the 1.x default can therefore stop after the first failed item even though they never hand-built a config. Explicitly direct them to MapConfig(completion_config=CompletionConfig.all_completed()) to preserve process-all behavior.

[github-actions]

Codex AI review

[P2] Document the predicate's initial invocation. should_complete runs before any branch is scheduled, with completed_count == 0 and unscheduled item statuses set to None, and also runs on suspension state changes. Without this, a predicate may dereference a missing status, fail the batch, or return complete_batch() immediately and execute no branches. Add these invocation and None-handling requirements.

[github-actions]

Codex AI review

Two migration-guide gaps could cause upgraded workflows to skip work or fail unexpectedly. The Python change is documentation-only; no runtime tests were executed under the review constraints.

Reviewed commit 6f1d145c148c5b2064f1c0e3c18e38af84ba2305. Workflow run