docs: reorganize Orleans documentation navigation - #10336
Merged
ReubenBond merged 9 commits intoAug 7, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Reorganizes the Orleans documentation site into updated task/operations/architecture/migration/streaming tracks, updates navigation and samples entry points, and adds explicit legacy URL redirects which preserve anchors for retired pages.
Changes:
- Updates DocFX → Starlight sidebar generation to support absolute site-root links (for example,
/samples/) and adjusts tests accordingly. - Adds explicit redirect mapping (
redirects.json) and integrates it into the legacy redirect generator and rendered-output audit. - Large-scale docs refresh: adds new Orleans 10 operational, migration, streaming, and runtime-architecture pages while removing legacy/retired tutorials and platform guidance (for example, Service Fabric/Cloud Services content and older snippet projects).
Show a summary per file
| File | Description |
|---|---|
| docs/site/tests/docfx.test.mjs | Extends sidebar conversion test coverage to include an absolute /samples/ link. |
| docs/site/src/data/redirects.json | Adds explicit, anchor-preserving redirects for retired legacy entry points. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Silo/Silo.csproj | Removes legacy minimal tutorial snippet project file. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Silo/Program.cs | Removes legacy minimal tutorial silo snippet source. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/minimal.sln | Removes legacy minimal tutorial solution file. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Grains/HelloGrain.cs | Removes legacy minimal tutorial grain snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Grains/Grains.csproj | Removes legacy minimal tutorial grains project file. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/GrainInterfaces/IHello.cs | Removes legacy minimal tutorial interface snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/GrainInterfaces/GrainInterfaces.csproj | Removes legacy minimal tutorial interfaces project file. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Client/Program.cs | Removes legacy minimal tutorial client snippet source. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Client/Client.csproj | Removes legacy minimal tutorial client project file. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/SiloProgram.cs | Removes legacy Hello World tutorial silo snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/IHello.cs | Removes legacy Hello World tutorial interface snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/helloworld.csproj | Removes legacy Hello World tutorial project file. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/HelloGrain.cs | Removes legacy Hello World tutorial grain snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/ClientProgram.cs | Removes legacy Hello World tutorial client snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/Program.cs | Removes legacy Orleans v3 custom-storage snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/FileSiloBuilderExtensions.cs | Removes legacy Orleans v3 custom-storage snippet extension methods. |
| docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/FileGrainStorageOptions.cs | Removes legacy Orleans v3 custom-storage options snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/FileGrainStorageFactory.cs | Removes legacy Orleans v3 custom-storage factory snippet. |
| docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/custom-storage.csproj | Removes legacy Orleans v3 custom-storage project file. |
| docs/site/src/content/docs/tutorials-and-samples/overview-helloworld.md | Removes legacy Hello World tutorial page (replaced by new quickstart/redirects). |
| docs/site/src/content/docs/tutorials-and-samples/adventure.md | Updates sample instructions and refreshes metadata date. |
| docs/site/src/content/docs/streaming/streaming-operations.md | Adds new Orleans 10 streaming operations/tuning guidance. |
| docs/site/src/content/docs/streaming/snippets/streaming/streaming.csproj | Updates streaming snippet package set/versions for current Orleans 10 examples. |
| docs/site/src/content/docs/streaming/snippets/streaming/ImplicitSubscriptions.cs | Reworks implicit subscription example to a typed telemetry scenario. |
| docs/site/src/content/docs/streaming/snippets/streaming/ExplicitSubscriptions.cs | Reworks explicit subscription example with typed telemetry and subscribe/unsubscribe APIs. |
| docs/site/src/content/docs/streaming/snippets/streaming/BasicStreaming.cs | Replaces basic streaming examples with typed contracts, identities, and a producer grain. |
| docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/streams-quickstart.csproj | Removes legacy Orleans v3 streams quickstart snippet project. |
| docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/StreamConfiguration.cs | Removes legacy Orleans v3 streams configuration snippet. |
| docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/ReceiverGrain.cs | Removes legacy Orleans v3 receiver-grain snippet. |
| docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/ProducerGrain.cs | Removes legacy Orleans v3 producer-grain snippet. |
| docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/IRandomReceiver.cs | Removes legacy Orleans v3 receiver interface snippet. |
| docs/site/src/content/docs/streaming/pubsub-storage.md | Adds focused PubSubStore configuration guidance. |
| docs/site/src/content/docs/streaming/delivery-semantics.md | Adds provider-aware delivery/ordering/replay/recovery guidance for streams. |
| docs/site/src/content/docs/resources/orleans-thinking-big-and-small.md | Refreshes and modernizes “big vs small” resource article framing for Orleans 10. |
| docs/site/src/content/docs/resources/orleans-architecture-principles-and-approach.md | Rewrites architecture principles page for Orleans 10 framing and terminology. |
| docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/cosmos/Program.cs | Adds Cosmos-based deployment quickstart snippet. |
| docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/cosmos/Cosmos.csproj | Adds Cosmos quickstart snippet project file. |
| docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/azure-storage/Program.cs | Adds Azure Table Storage-based deployment quickstart snippet. |
| docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/azure-storage/AzureStorage.csproj | Adds Azure Table Storage quickstart snippet project file. |
| docs/site/src/content/docs/migration/snippets/Orleans10MigrationSnippets.csproj | Adds a dedicated Orleans 10 migration snippets project for compile validation. |
| docs/site/src/content/docs/migration/snippets/Orleans10MigrationExamples.cs | Adds Orleans 10 migration examples (timeouts, placement, filters, timers, serialization). |
| docs/site/src/content/docs/migration/deployment-and-rollback.md | Adds major-upgrade deployment and rollback prerequisites/checklists. |
| docs/site/src/content/docs/migration/8-to-10.md | Adds Orleans 8→10 migration path with explicit checkpoints and validation steps. |
| docs/site/src/content/docs/migration/7-to-10.md | Adds Orleans 7→10 migration path with sequencing and compatibility notes. |
| docs/site/src/content/docs/migration/3-to-7-archive.md | Adds archived Orleans 3→7 migration notes and warnings. |
| docs/site/src/content/docs/index.yml | Updates docs hub page metadata and refreshes highlighted links for new structure. |
| docs/site/src/content/docs/implementation/runtime-architecture.md | Adds new runtime call-path architecture page (client → messaging → placement → activation). |
| docs/site/src/content/docs/implementation/provider-authoring.md | Adds new provider authoring architecture guidance. |
| docs/site/src/content/docs/implementation/index.md | Replaces/expands implementation track index into a structured runtime-architecture guide. |
| docs/site/src/content/docs/implementation/activation-lifecycle.md | Adds detailed activation lifecycle/migration page with diagrams and invariants. |
| docs/site/src/content/docs/host/snippets/snippets.sln | Adds the new hosting snippets project to the snippets solution. |
| docs/site/src/content/docs/host/snippets/hosting/Hosting.csproj | Introduces a hosting snippet project with provider package references. |
| docs/site/src/content/docs/host/snippets/aspire/Silo/SiloProgram.cs | Updates Aspire snippets to use Azure Tables keyed service clients. |
| docs/site/src/content/docs/host/snippets/aspire/Silo/Silo.csproj | Adds Azure Storage clustering/persistence/reminders packages to Aspire silo snippet. |
| docs/site/src/content/docs/host/snippets/aspire/AppHost/AppHostExamples.cs | Adjusts Aspire app host example to use tables for grain storage. |
| docs/site/src/content/docs/host/snippets/aspire/AppHost/AppHost.csproj | Updates Aspire app host SDK and package references. |
| docs/site/src/content/docs/host/monitoring/snippets/observability/Program.cs | Adds a concrete OpenTelemetry configuration example for Orleans hosting. |
| docs/site/src/content/docs/host/monitoring/snippets/observability/Observability.csproj | Adds an Observability snippet project to compile the OTel example. |
| docs/site/src/content/docs/host/monitoring/silo-error-code-monitoring.md | Removes stale error-code table and points readers to source/xref and signal-based guidance. |
| docs/site/src/content/docs/host/monitoring/signals.md | Adds a new “interpret signals” observability guide. |
| docs/site/src/content/docs/host/monitoring/client-error-code-monitoring.md | Removes stale client error-code table and points to source/xref and troubleshooting guides. |
| docs/site/src/content/docs/host/heterogeneous-silos.md | Updates heterogeneous silo guidance for Orleans 10 patterns and current options. |
| docs/site/src/content/docs/host/configuration-guide/shutting-down-orleans.md | Rewrites shutdown guidance around Generic Host ownership and shutdown budgets. |
| docs/site/src/content/docs/host/configuration-guide/serialization.md | Links configuration guide to new serialization internals page. |
| docs/site/src/content/docs/host/configuration-guide/configuring-garbage-collection.md | Modernizes GC guidance and aligns it with container limits and activation management. |
| docs/site/src/content/docs/grains/oneway.md | Reframes one-way calls with clearer semantics and updated example. |
| docs/site/src/content/docs/grains/grain-versioning/version-selector-strategy.md | Updates selector strategy explanations and clarifies behavior. |
| docs/site/src/content/docs/grains/grain-versioning/grain-versioning.md | Modernizes versioning overview with explicit routing semantics and limitations. |
| docs/site/src/content/docs/grains/grain-versioning/deploying-new-versions-of-grains.md | Rewrites deployment strategy guidance, including rollback and observability. |
| docs/site/src/content/docs/grains/grain-versioning/compatible-grains.md | Reworks compatibility strategies page with explicit numeric rules and cautions. |
| docs/site/src/content/docs/grains/grain-persistence/snippets/persistence/Interfaces.cs | Updates persistence snippet interface for nullable ETag and optional cancellation token overloads. |
| docs/site/src/content/docs/grains/grain-persistence/dynamodb-storage.md | Rewrites DynamoDB provider guidance with production-oriented configuration notes. |
| docs/site/src/content/docs/grains/grain-persistence/azure-cosmos-db.md | Rewrites Cosmos DB storage guidance with clearer separation from clustering and migration cautions. |
| docs/site/src/content/docs/grains/event-sourcing/replicated-instances.md | Updates JournaledGrain replication/conflict guidance and clarifies boundaries. |
| docs/site/src/content/docs/grains/event-sourcing/notifications.md | Modernizes notification guidance and clarifies callback semantics. |
| docs/site/src/content/docs/grains/event-sourcing/log-consistency-providers.md | Refactors provider comparison and clarifies durability/scale constraints. |
| docs/site/src/content/docs/grains/event-sourcing/journaledgrain-diagnostics.md | Updates diagnostics guidance and clarifies intended use. |
| docs/site/src/content/docs/grains/event-sourcing/index.md | Expands event sourcing overview and distinguishes supported vs experimental journaling. |
| docs/site/src/content/docs/grains/event-sourcing/immediate-vs-delayed-confirmation.md | Updates confirmation semantics guidance and aligns with Orleans scheduling model. |
| docs/site/src/content/docs/deployment/upgrades.md | Adds new upgrade/shutdown/scale-in operational guidance page. |
| docs/site/src/content/docs/deployment/troubleshooting-azure-cloud-services-deployments.md | Removes retired Azure Cloud Services troubleshooting page. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/Program.cs | Removes legacy Service Fabric stateless hosting snippet. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/PackageRoot/ServiceManifest.xml | Removes legacy Service Fabric manifest snippet. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/PackageRoot/Config/Settings.xml | Removes legacy Service Fabric settings snippet. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/OrleansHostedStatelessService.cs | Removes legacy Service Fabric wrapper type snippet. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/Orleans.ServiceFabric.Stateless.csproj | Removes legacy Service Fabric snippet project. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/HostedServiceCommunicationListener.cs | Removes legacy Service Fabric communication listener snippet. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/snippets.5000.json | Removes legacy Visual Studio snippet metadata. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/service-fabric.sln | Removes legacy Service Fabric solution file. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Local.5Node.xml | Removes legacy Service Fabric publish profile. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Local.1Node.xml | Removes legacy Service Fabric publish profile. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Cloud.xml | Removes legacy Service Fabric publish profile. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/packages.config | Removes legacy Service Fabric packages.config. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/Orleans.ServiceFabric.App.sfproj | Removes legacy Service Fabric application project file. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Local.5Node.xml | Removes legacy Service Fabric app parameters file. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Local.1Node.xml | Removes legacy Service Fabric app parameters file. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Cloud.xml | Removes legacy Service Fabric app parameters file. |
| docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationPackageRoot/ApplicationManifest.xml | Removes legacy Service Fabric application manifest. |
| docs/site/src/content/docs/deployment/snippets/consul/Silo/Silo.csproj | Removes legacy Consul snippet project. |
| docs/site/src/content/docs/deployment/snippets/consul/Silo/Properties/launchSettings.json | Removes legacy Consul snippet launch settings. |
| docs/site/src/content/docs/deployment/snippets/consul/Silo/Program.cs | Removes legacy Consul snippet program. |
| docs/site/src/content/docs/deployment/service-fabric.md | Removes legacy Service Fabric hosting guidance page. |
| docs/site/src/content/docs/deployment/production-readiness.md | Adds a production-readiness checklist page. |
| docs/site/src/content/docs/deployment/platform-guides.md | Adds platform requirements/guidance page for evaluating hosting platforms. |
| docs/site/src/content/docs/deployment/networking.md | Adds a topology/networking/clustering page with explicit endpoint guidance. |
| docs/site/src/content/docs/deployment/index.md | Replaces “Run an Orleans application” with a structured deploy/operate track index. |
| docs/site/src/content/docs/deployment/includes/deployment/create-service-principal.md | Removes legacy service principal creation include (secrets-based guidance). |
| docs/site/src/content/docs/deployment/includes/deployment/create-github-secret.md | Removes legacy GitHub secret creation include (secrets-based guidance). |
| docs/site/src/content/docs/deployment/includes/deployment/create-azure-resources.md | Removes legacy Azure resource group include. |
| docs/site/src/content/docs/deployment/health-and-observability.md | Adds health/readiness/liveness and observability design guidance. |
| docs/site/src/content/docs/deployment/disaster-recovery.md | Adds backup/restore/disaster recovery guidance. |
| docs/site/src/content/docs/deployment/capacity-planning.md | Adds capacity planning and scaling guidance page. |
| docs/site/src/content/docs/dashboard/snippets/secure-dashboard/SecureDashboard.csproj | Adds a secure dashboard snippet project. |
| docs/site/src/content/docs/dashboard/snippets/secure-dashboard/Program.cs | Adds secure dashboard configuration example with authn/z and routing. |
| docs/site/scripts/lib/docfx.mjs | Updates sidebar generation to allow absolute-path links and skip local file validation for them. |
| docs/site/scripts/generate-legacy-redirects.mjs | Integrates explicit redirects, adds safer output path resolution, and validates redirect targets. |
| docs/site/scripts/audit-output.mjs | Integrates explicit redirects validation in rendered output audit and adds safer output path resolution. |
| docs/site/README.md | Documents the new explicit redirect override mechanism. |
| docs/site/astro.config.mjs | Removes the extra “Reference” sidebar section and relies on toc/sidebar generation instead. |
Copilot's findings
- Files reviewed: 126/223 changed files
- Comments generated: 1
Contributor
There was a problem hiding this comment.
Copilot's findings
Suppressed comments (1)
docs/site/scripts/audit-output.mjs:44
outputPathForassumes the route starts with/orleans/and relies on slicing to compute the relative path. Ifredirects.jsonever contains an unexpected key (missing the prefix, containing.., etc), this can produce confusing audit results instead of failing fast. Consider validating the route format here the same waygenerate-legacy-redirects.mjsdoes (prefix + no..) before resolving paths.
function outputPathFor(route) {
const relativeRoute = decodeURIComponent(route.slice('/orleans/'.length));
const outputPath = relativeRoute.endsWith('/')
? path.resolve(distRoot, relativeRoute, 'index.html')
: path.resolve(distRoot, relativeRoute);
const relativeOutput = path.relative(distRoot, outputPath);
if (relativeOutput.startsWith(`..${path.sep}`) || path.isAbsolute(relativeOutput)) {
throw new Error(`Compatibility path '${route}' resolves outside the output directory.`);
}
return outputPath;
}
- Files reviewed: 129/256 changed files
- Comments generated: 1
ReubenBond
added a commit
to ReubenBond/orleans
that referenced
this pull request
Aug 3, 2026
Preserve the published enforcement lineage while making the fully validated dotnet#10336 navigation head its dependency. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2c7276b1-2a5b-48dc-a687-fa6719a5df83
ReubenBond
added a commit
to ReubenBond/orleans
that referenced
this pull request
Aug 3, 2026
Add the validated Kubernetes Aspire and resource guidance from the refreshed dotnet#10336 navigation lineage without rewriting published enforcement history. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2c7276b1-2a5b-48dc-a687-fa6719a5df83
ReubenBond
marked this pull request as ready for review
August 7, 2026 23:37
3 tasks
This was referenced Aug 28, 2026
Merged
This was referenced Sep 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Dependencies
Depends on #10327, #10328, #10329, #10330, #10331, #10332, #10333, #10334, and #10335.
This stacked PR includes the dependency commits so the complete documentation hierarchy can be validated together. As each dependency merges, its aggregate ancestor commits will disappear from this PR diff, leaving the shared navigation and integration changes.
Microsoft Reviewers: Open in CodeFlow