Skip to content

docs: make package READMEs lean and usage-first - #914

Merged
ParidelPooya merged 1 commit into
mainfrom
docs/lean-readmes
Nov 9, 2026
Merged

ParidelPooya merged 1 commit into
mainfrom
docs/lean-readmes

Conversation

@ParidelPooya

Copy link
Copy Markdown
Contributor

What changed

Four package READMEs now follow one shape: install, a quick start, common uses, short advanced notes, and reference links. The long sections moved to docs files next to each package. Moved text keeps its wording.

Package Words before Words after
aws-durable-execution-sdk-python 1847 666
aws-durable-execution-sdk-python-extras 8168 1126
aws-durable-execution-sdk-python-microvm-worker 5064 823
aws-durable-execution-sdk-python-testing 780 506

The testing README was already short. Most of what remains is code.

PyPI uses each README as the package description. So README links to repo files use absolute GitHub URLs.

Where the moved content went

  • Core: the plugin sections went to packages/aws-durable-execution-sdk-python/docs/plugins.md. These cover the factory contract, OpenTelemetry views, the invocation worker lifecycle, and chained-invoke propagation. The two links from docs/migration-2.x-to-3.0.md now point at that file.
  • Extras: everything after the intro went to packages/aws-durable-execution-sdk-python-extras/docs/microvm.md. This covers delivery, errors, retry tiers, limits, permissions, sessions, suspending, the state check, subtypes, and best practices. Keeping it in one file keeps every internal anchor valid.
  • MicroVM worker: the handler rules and every section after Usage went to packages/aws-durable-execution-sdk-python-microvm-worker/docs/worker.md.
  • Testing: the paragraph about callback failures without diagnostics went to a new section at the end of packages/aws-durable-execution-sdk-python-testing/docs/error-responses.md.

The READMEs keep the MicroVM rules below as product behavior:

  1. The SDK never calls ResumeMicrovm.
  2. A session that suspends must set idlePolicy.autoResumeEnabled. Setting it is the developer's job.
  3. Set maxIdleDurationSeconds above maximumDurationInSeconds.
  4. With suspend_after, the developer is responsible for parallel operations on the same session.

Fixed or dropped as stale

  • Extras subtypes note: the old text said the Python SDK does not accept custom subtypes yet. The core SDK now has sub_type on StepConfig, ChildConfig, and CallbackConfig. The note now says that this package does not set it yet.
  • Testing quick start: runner.run(..., timeout=10) emits a DeprecationWarning. The example now uses execution_timeout.
  • Core README: the "Key Features" list and the packages table were dropped. The Reference section links to the testing package.
  • Testing README: the table of contents, the "Key features" list under error handling, and the hatch tl;dr were dropped. The Reference section links to the contributing guide.

How the examples were checked

  • Each README code block was extracted. Each complete block was type-checked with mypy against the packages on main and imported.
  • Examples that continue an earlier example were placed in that context and type-checked. The MicroVM configs in them were constructed at runtime, so their validation ran.
  • The core and testing examples ran with DurableFunctionTestRunner, with DeprecationWarning set to error.
  • A script checked relative links and anchors in every changed Markdown file.
  • hatch build ran for the four packages, and twine check passed on the wheels and sdists.
  • lintcommit.py passed.

Rewrite the core, extras, microvm-worker, and testing READMEs. Each
README now has install, a quick start, common uses, short advanced
notes, and links to reference docs.

Move the long sections to docs files next to each package:
- core: docs/plugins.md
- extras: docs/microvm.md
- microvm-worker: docs/worker.md
- testing: callback-failure notes into docs/error-responses.md

Point the 2.x to 3.0 migration guide links at docs/plugins.md.

Update the extras subtypes note: the core SDK now accepts a custom
sub_type. Replace the deprecated run(timeout=...) in the testing
example with execution_timeout.
@ParidelPooya
ParidelPooya marked this pull request as ready for review November 9, 2026 17:28
@ParidelPooya
ParidelPooya merged commit e4bbbcd into main Nov 9, 2026
44 of 46 checks passed
@ParidelPooya
ParidelPooya deleted the docs/lean-readmes branch November 9, 2026 17:44
@SilanHe SilanHe mentioned this pull request Nov 9, 2026
3 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants