Cleanup readme #48

greenie-msft · 2025-04-02T18:39:14Z

I made some updates to the README. Here's a summary of the changes:

Main topics have been moved to their own separate documents outside of the main README.
Legacy content has been removed
The Getting Started section now uses one of the DTS quickstarts hosted in the repository.

cgillum · 2025-04-06T15:05:27Z

docs/features.md

+
+Orchestrations can be suspended using the `suspend_orchestration` client API and will remain suspended until resumed using the `resume_orchestration` client API. A suspended orchestration will stop processing new events, but will continue to buffer any that happen to arrive until resumed, ensuring that no data is lost. An orchestration can also be terminated using the `terminate_orchestration` client API. Terminated orchestrations will stop processing new events and will discard any buffered events.
+
+### Retry policies (TODO)


This (TODO) can be removed

cgillum · 2025-04-06T15:05:32Z

docs/features.md

+
+Orchestrations can wait for external events using the `wait_for_external_event` API. External events are useful for implementing human interaction patterns, such as waiting for a user to approve an order before continuing.
+
+### Continue-as-new (TODO)


This (TODO) can be removed

cgillum · 2025-04-06T15:06:24Z

docs/contributing.md

@@ -0,0 +1,13 @@
+# Contributing


A CONTRIBUTING.md (all caps) file is typically expected to exist at the root of a repo.

cgillum · 2025-04-06T15:07:22Z

docs/supported-patterns.md

+
+As an aside, you'll also notice that the example orchestration above works with custom business objects. Support for custom business objects includes support for custom classes, custom data classes, and named tuples. Serialization and deserialization of these objects is handled automatically by the SDK.
+
+You can find the full sample [here](./examples/human_interaction.py).


Do all the links to samples need to be fixed now that you've changed the location of this content?

Suggested change

You can find the full sample [here](./examples/human_interaction.py).

You can find the full sample [here](../examples/human_interaction.py).

cgillum · 2025-04-06T15:10:36Z

examples/dts/sub-orchestrations-with-fan-out-fan-in/README.md

@@ -0,0 +1,102 @@
+# Portable SDK Sample for Sub Orchestrations and Fan-out / Fan-in


Shouldn't this go directly under examples? Also, if we're updating the focus of the repo to just be DTS, then we don't need a dts subfolder under examples. All samples can assume DTS and have corresponding instructions for using the emulator.

cgillum · 2025-04-06T15:15:46Z

examples/dts/sub-orchestrations-with-fan-out-fan-in/README.md

+
+Create a Scheduler:
+```bash
+az durabletask scheduler create --resource-group --name --location --ip-allowlist "[0.0.0.0/0]" --sku-capacity 1 --sku-name "Dedicated" --tags "{'myattribute':'myvalue'}"


I suggest we guide readers to use the emulator rather than creating resources in Azure. That will save them a ton of time and effort when they're still learning. Let's have separate instructions and/or more substantial samples for configuring apps with DTS in Azure.

cgillum · 2025-04-06T15:17:16Z

examples/dts/sub-orchestrations-with-fan-out-fan-in/README.md

+docker run --name dtsemulator -d -p 8080:8080 mcr.microsoft.com/dts/dts-emulator:v0.0.4
+```
+
+3. Set the Environment Variables:


Let's remove environment variables from the local emulator setup instructions. The sample code can assume localhost and default if these variables don't exist. This will save users a lot of time and effort when getting started.

cgillum · 2025-04-06T15:18:08Z

examples/dts/sub-orchestrations-with-fan-out-fan-in/orchestrator.py

+if taskhub_name:
+    print(f"The value of TASKHUB is: {taskhub_name}")
+else:
+    print("TASKHUB is not set. Please set the TASKHUB environment variable to the name of the taskhub you wish to use")


Again, I suggest we remove this requirement. We can assume default values for emulator usage if these environment variables aren't sent.

cgillum · 2025-04-06T15:19:16Z

examples/dts/sub-orchestrations-with-fan-out-fan-in/worker.py

+if taskhub_name:
+    print(f"The value of TASKHUB is: {taskhub_name}")
+else:
+    print("TASKHUB is not set. Please set the TASKHUB environment variable to the name of the taskhub you wish to use")


Same comment about default values for these environment variables.

cgillum · 2025-04-06T15:20:59Z

README.md

+- [Available Features](./docs/features.md)
+- [Getting Started](./docs/getting-started.md)
+- [Development Guide](./docs/development.md) 
+- [Contributing Guide](./docs/development.md)

 ## Trademarks


nit: I see you're removing whitespace between titles and content, but MS Learn markdown conventions require an extra newline between section titles and content. I suggest we do the same here.

Suggested VS Code extension: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint

cgillum · 2025-04-10T22:26:30Z

Looks like the removal of the dts directory caused a CI issue, so we probably need to also update the CI yaml contents.

Nicholas Greenfield added 4 commits April 2, 2025 11:22

First pass at cleaning up the readme

8898b69

Fix README instructions to add pre-reqs

3baae47

continue to clean up instructions

8ee7098

Restore development text

a6f1ee6

cgillum requested changes Apr 6, 2025

View reviewed changes

Address PR feedback and change all examples to use DTS

cb17781

cgillum approved these changes Apr 10, 2025

View reviewed changes

cgillum self-requested a review April 10, 2025 22:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cleanup readme #48

Cleanup readme #48

greenie-msft commented Apr 2, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum Apr 6, 2025

cgillum commented Apr 10, 2025


		Orchestrations can be suspended using the `suspend_orchestration` client API and will remain suspended until resumed using the `resume_orchestration` client API. A suspended orchestration will stop processing new events, but will continue to buffer any that happen to arrive until resumed, ensuring that no data is lost. An orchestration can also be terminated using the `terminate_orchestration` client API. Terminated orchestrations will stop processing new events and will discard any buffered events.

		### Retry policies (TODO)


		Orchestrations can wait for external events using the `wait_for_external_event` API. External events are useful for implementing human interaction patterns, such as waiting for a user to approve an order before continuing.

		### Continue-as-new (TODO)


		As an aside, you'll also notice that the example orchestration above works with custom business objects. Support for custom business objects includes support for custom classes, custom data classes, and named tuples. Serialization and deserialization of these objects is handled automatically by the SDK.

		You can find the full sample [here](./examples/human_interaction.py).

	You can find the full sample [here](./examples/human_interaction.py).
	You can find the full sample [here](../examples/human_interaction.py).

		@@ -0,0 +1,102 @@
		# Portable SDK Sample for Sub Orchestrations and Fan-out / Fan-in

Cleanup readme #48

Are you sure you want to change the base?

Cleanup readme #48

Conversation

greenie-msft commented Apr 2, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cgillum commented Apr 10, 2025