What are you really trying to do?
Two unrelated audiences read this file. Someone evaluating or using the package wants installation
and usage. Someone contributing to the repository wants to know how to build the bridge, run the
tests, and regenerate code. Both are currently served by one 1,434-line document, and each has to
scroll past the other's material.
Describe the problem
The root README.md is not just the repository landing page — it is the NuGet package page.
src/Temporalio/Temporalio.csproj packs it directly:
<None Include="../../README.md" Pack="true" PackagePath="\" />
So the published page for Temporalio ends with a ## Development section explaining how to
build the Rust bridge, run the test suite, regenerate protobuf types, and configure formatting in
VS Code. None of that is actionable for someone who has installed the package.
In the other direction, a would-be contributor opening the repository has to scroll past 1,317 lines of usage
documentation before reaching contributing instructions at line 1318.
Every other package in this repository already does the thing being proposed here — each has its
own README.md next to its project and packs it locally:
src/Temporalio.Extensions.Aws.Lambda/README.md 157 lines
src/Temporalio.Extensions.Aws.Lambda.OpenTelemetry/README.md 71 lines
src/Temporalio.Extensions.DiagnosticSource/README.md 47 lines
src/Temporalio.Extensions.Gcp.CloudRun.OpenTelemetry/README.md 117 lines
src/Temporalio.Extensions.Hosting/README.md 197 lines
src/Temporalio.Extensions.OpenTelemetry/README.md 243 lines
Temporalio is the only package that reaches up to the repository root for its readme.
Proposed change
- Move the library content — the header, Quick Start, and Usage sections, lines 1 to 1317 — to
src/Temporalio/README.md.
- Change
Temporalio.csproj to pack README.md from its own directory, matching the six
extension projects.
- Leave the root
README.md as a repository overview: what this repo contains, where the packages
are, the ## Development section that is already there, and a prominent link to the library
readme.
What are you really trying to do?
Two unrelated audiences read this file. Someone evaluating or using the package wants installation
and usage. Someone contributing to the repository wants to know how to build the bridge, run the
tests, and regenerate code. Both are currently served by one 1,434-line document, and each has to
scroll past the other's material.
Describe the problem
The root
README.mdis not just the repository landing page — it is the NuGet package page.src/Temporalio/Temporalio.csprojpacks it directly:So the published page for
Temporalioends with a## Developmentsection explaining how tobuild the Rust bridge, run the test suite, regenerate protobuf types, and configure formatting in
VS Code. None of that is actionable for someone who has installed the package.
In the other direction, a would-be contributor opening the repository has to scroll past 1,317 lines of usage
documentation before reaching contributing instructions at line 1318.
Every other package in this repository already does the thing being proposed here — each has its
own
README.mdnext to its project and packs it locally:Temporaliois the only package that reaches up to the repository root for its readme.Proposed change
src/Temporalio/README.md.Temporalio.csprojto packREADME.mdfrom its own directory, matching the sixextension projects.
README.mdas a repository overview: what this repo contains, where the packagesare, the
## Developmentsection that is already there, and a prominent link to the libraryreadme.