[Feature Request] Guide against single-file structure

[lorensr]

Is your feature request related to a problem? Please describe.

Given this single-file pattern of running a Workflow inside a Worker:

samples-python/hello/hello_activity.py

Lines 47 to 64 in 7b39449

	# Run a worker for the workflow
	async with Worker(
	client,
	task_queue="hello-activity-task-queue",
	workflows=[GreetingWorkflow],
	activities=[compose_greeting],
	):
	# While the worker is running, use the client to run the workflow and
	# print out its result. Note, in many production setups, the client
	# would be in a completely separate process from the worker.
	result = await client.execute_workflow(
	GreetingWorkflow.run,
	"World",
	id="hello-activity-workflow-id",
	task_queue="hello-activity-task-queue",
	)
	print(f"Result: {result}")

there is potential (and one past instance I know of) for people learning based off of samples to think that in order to run a Workflow, you need to run it inside an async with Worker. When they try to develop an application based on that paradigm, they run into a number of issues.

Describe the solution you'd like

Make it clear that when developing, we recommend:

• running a worker separately from workflows
• defaulting to a single worker for all workflows, not one worker per workflow

We could make it clear by structuring all samples that way. OTOH I like the brevity of the single file samples. Another possibility is changing the comment. The drawbacks to that are:

• some people don't read comments
• the comment might not be clear, unless you point to a multi-file sample, what exactly we recommend doing

Comment is currently:

# While the worker is running, use the client to run the workflow and
# print out its result. Note, in many production setups, the client
# would be in a completely separate process from the worker.

Perhaps could be:

# Use the client to run the workflow and print out its result. 
# NOTE: when developing, we recommend starting out running a 
# single worker that has all your workflow and activities and
# running client code in a separate process. See, for example,
# how the encryption sample has a separate files to run:
# worker.py runs the worker and starter.py uses the client.

[cretz]

I support any changes you suggest to this effect. We initially wanted single file examples for clarity. I support breaking them into multiple files, changing the comment, or maybe even the best option - same file but different paths based on arg.

[mbernier]

I was thinking about suggesting a change where the first example is a single file and has a comment that says something like the above to say "Yo, this is a single file for a simple hello world. All other examples break this into multiple files, you should not build your app in the single file way".

Something extremely clear and to the point.

The other nice thing about multi-file examples, is that a README could be included to explain what is going on with that specific example and why it is included.

[cretz]

you should not build your app in the single file way

FWIW this is subjective based on use case. Many people may have the same app starting the workflow as running it. It's just that most people choose to start somewhere separate than they run.

The other nice thing about multi-file examples, is that a README could be included to explain what is going on with that specific example and why it is included.

This is what we do with all of our multi-file samples in this repo. The only single file examples that exist are the "hello" ones because they are so trivial they would just muddy up the waters quadrupling the file/dir count. Go and TypeScript suffer from this a bit (you can't differentiate the involved samples from the simple snippets due to them all being clumped together). Java was nice enough to have single-file hello samples like we do here and it hasn't been a problem for them. Having said that, if y'all want to break these out I totally support it though we should probably apply to Java if this is the new rule and single file samples are a problem.

[cretz]

We're gonna move to multi-file samples I think, ref #67