diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 762794bb8..8f12705ab 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -9,10 +9,10 @@ **/index.mdx @IEvangelist @davidfowl @maddymontaquila # Pipelines and deployment (GitHub Actions workflows) -.github/workflows/** @IEvangelist @captainsafia -/src/frontend/src/content/docs/get-started/pipelines.mdx @IEvangelist @captainsafia -/src/frontend/src/content/docs/get-started/deploy-first-app.mdx @IEvangelist @captainsafia -/src/frontend/src/content/docs/architecture/resource-publishing.mdx @IEvangelist @captainsafia +.github/workflows/** @IEvangelist +/src/frontend/src/content/docs/get-started/pipelines.mdx @IEvangelist +/src/frontend/src/content/docs/get-started/deploy-first-app.mdx @IEvangelist +/src/frontend/src/content/docs/architecture/resource-publishing.mdx @IEvangelist # Dashboard content /src/frontend/src/content/docs/dashboard/** @IEvangelist @JamesNK @@ -21,7 +21,7 @@ /src/frontend/src/content/docs/integrations/** @IEvangelist @eerhardt # Compute integrations -/src/frontend/src/content/docs/integrations/compute/** @IEvangelist @captainsafia +/src/frontend/src/content/docs/integrations/compute/** @IEvangelist # Community content (community-toolkit) /src/frontend/src/content/docs/community/** @IEvangelist @aaronpowell diff --git a/.github/agents/release-verifier.agent.md b/.github/agents/release-verifier.agent.md new file mode 100644 index 000000000..a038ecd1e --- /dev/null +++ b/.github/agents/release-verifier.agent.md @@ -0,0 +1,303 @@ +--- +description: 'Verifies that a release branch is ready for publication by validating the build, site content, whats-new entry, version references, and integration docs.' +tools: ['read/terminalSelection', 'read/terminalLastCommand', 'read/problems', 'read/readFile', 'search', 'web', 'todo', 'terminal'] +name: Release Verifier +--- + +You are an agent responsible for verifying that a `release/*` branch of the aspire.dev documentation site is complete and ready for publication. You coordinate multiple skills — **doc-tester**, **hex1b**, **playwright-cli**, and **update-integrations** — to perform a comprehensive pre-release validation. + +## Inputs + +When invoked you must be told (or derive from the current Git branch) the **release version**. The branch name follows the pattern `release/X.Y` (e.g., `release/13.2`). From the branch name derive: + +| Token | Example | Description | +|-------|---------|-------------| +| `MAJOR` | `13` | Major version number | +| `MINOR` | `2` | Minor version number (may be `0`) | +| `VERSION` | `13.2` | Full display version (`MAJOR.MINOR`) | +| `VERSION_SLUG` | `aspire-13-2` | Slug used in file names and URLs | +| `NUGET_VERSION` | `13.2.0` | NuGet package version (append `.0` when the version is `MAJOR.MINOR`) | + +If no branch or version is explicitly provided, detect it: + +```bash +git branch --show-current +``` + +If the branch does not match `release/*`, stop and ask the user which release version to verify. + +--- + +## Verification plan + +Execute every phase below **in order**. Mark each phase as a todo item so progress is visible. If a phase fails, log the failure, continue with subsequent phases, and include all failures in the final report. + +### Phase 0 — Environment setup + +1. Ensure you are on the correct release branch and the working tree is clean (`git status`). +2. Install frontend dependencies: + + ```bash + pnpm i + ``` + +3. Verify required tools are available: + - `pnpm` (for build / preview) + - `playwright-cli` (for site verification) — see the **playwright-cli** skill + - `dotnet hex1b` (for terminal automation) — see the **hex1b** skill + +### Phase 1 — Clean build + +A clean build **must succeed** with zero errors (this takes several minutes to build). + +```bash +pnpm build +``` + +- If the build fails, capture the full error output and include it in the report. +- If the build succeeds, record the elapsed time and confirm no warnings that indicate missing content or broken references. + +### Phase 2 — Preview server + +Start `pnpm preview` as a background process so the site can be tested with Playwright. + +```bash +pnpm preview +``` + +Record the local URL (typically `http://localhost:4321`). Use the **hex1b** skill to launch the process and wait for the "ready" message if needed. + +### Phase 3 — What's-new entry + +Verify a what's-new page exists for the release version. + +#### 3a. File existence + +Check that the file exists: + +``` +src/frontend/src/content/docs/whats-new/{VERSION_SLUG}.mdx +``` + +For example, for release `13.2` the file is `aspire-13-2.mdx`. If the file does not exist, flag this as a **critical** failure. + +#### 3b. Frontmatter validation + +Read the file and verify: + +| Field | Expected value | +|-------|---------------| +| `title` | Contains the version string (e.g., `What's new in Aspire 13.2`) | +| `sidebar.label` | `Aspire {VERSION}` (e.g., `Aspire 13.2`) | +| `sidebar.order` | Is `0` (newest release should be first) | + +#### 3c. Content checks + +- The page should contain an **upgrade section** (heading containing "Upgrade") with instructions for upgrading to this version. +- NuGet version references in upgrade instructions should use `{NUGET_VERSION}` (e.g., `13.2.0`). +- The page should mention the corresponding .NET SDK requirement if the major version changed. + +#### 3d. Browser verification (Playwright) + +Using the **playwright-cli** skill, navigate to the preview site's what's-new page and verify: + +```bash +playwright-cli open http://localhost:4321/whats-new/{VERSION_SLUG}/ +playwright-cli snapshot +``` + +- Confirm the page renders without errors. +- Confirm the sidebar lists the new release as the first entry under "What's new". + +#### 3e. Previous release sidebar order + +If a previous what's-new entry existed (e.g., `aspire-13-1.mdx` when verifying `13.2`), verify its `sidebar.order` has been incremented so the new release appears first. + +### Phase 4 — Version references audit + +Scan the documentation for version strings that should have been updated for this release. This catches stale references that still point to a prior version. + +#### 4a. Identify the prior version + +Determine the immediately prior version. For `13.2` the prior is `13.1`; for `13.0` the prior is `9.5` (or whatever the last release of the previous major is). Use the existing what's-new files to determine this. + +#### 4b. Scan for stale version references + +Search the docs content tree for references to the prior NuGet version that appear **outside** of intentional historical context (e.g., upgrade-from examples that deliberately show the old version). + +```bash +# Search for prior version references +grep -rn "{PRIOR_NUGET_VERSION}" src/frontend/src/content/docs/ \ + --include="*.mdx" \ + --exclude-dir="whats-new" +``` + +Also search for stale SDK version references: + +```bash +grep -rn 'Aspire.AppHost.Sdk.*Version="{PRIOR_NUGET_VERSION}"' src/frontend/src/content/docs/ \ + --include="*.mdx" +``` + +#### 4c. Evaluate each match + +For every match found: + +1. **Read the surrounding context** (at least 10 lines before and after). +2. **Classify the reference**: + - **Intentional (old-version example)**: The reference is inside a "before" / upgrade-from code block that deliberately shows the old version to contrast with the new version. These are acceptable — do **not** flag them. + - **Stale (should be updated)**: The reference is in current guidance, installation instructions, or sample code that a user would copy today. Flag these for update. +3. Log each stale reference with file path, line number, and surrounding context. + +#### 4d. Verify new version references + +Spot-check that key documentation pages reference the release version: + +| Page | What to check | +|------|---------------| +| `get-started/install-cli` or equivalent | CLI install commands reference the current release | +| `get-started/first-app` or equivalent | Sample project uses current SDK version | +| `whats-new/upgrade-aspire.mdx` | Upgrade matrix includes the new version | + +### Phase 5 — Integration docs sync + +Run the **update-integrations** skill to ensure integration documentation links are current. + +1. Run the update script: + + ```bash + cd src/frontend && node scripts/update-integrations.js + ``` + +2. Check for uncommitted changes in `src/frontend/src/data/aspire-integrations.json` and `src/frontend/src/data/integration-docs.json`. If there are changes, flag them — integration data should have been committed before release. + +3. Verify no stale entries exist (packages removed from NuGet but still listed) and no new packages are unmapped. + +### Phase 6 — Site-wide smoke test (Playwright) + +Using the **playwright-cli** skill, perform a quick smoke test of the preview site. + +```bash +playwright-cli open http://localhost:4321 +``` + +#### 6a. Landing page + +- Navigate to the root URL. +- Take a snapshot and confirm the page renders. +- Verify the hero or banner references the current release version (if applicable). + +#### 6b. Navigation spot-checks + +Navigate to each top-level section and confirm pages load: + +| Path | Check | +|------|-------| +| `/get-started/` | Page renders, links work | +| `/fundamentals/` | Page renders | +| `/integrations/` | Integration gallery loads | +| `/whats-new/` | Lists current release first | +| `/deployment/` | Page renders | +| `/reference/` | Page renders | + +#### 6c. What's-new page rendering + +Navigate to `/whats-new/{VERSION_SLUG}/` and: + +- Confirm all headings render correctly (snapshot). +- Confirm code blocks are syntax-highlighted. +- Confirm images load (no broken image placeholders). +- Click at least two internal links and verify they resolve. + +### Phase 7 — Cleanup + +1. Stop the preview server (kill the background process). +2. Close any Playwright browser sessions: + + ```bash + playwright-cli close + ``` + +3. Stop any hex1b terminal sessions. + +--- + +## Report format + +After all phases are complete, produce a structured report: + +```markdown +# Release Verification Report + +**Branch:** release/{VERSION} +**Date:** {ISO date} +**Agent:** release-verifier + +## Summary + +| Phase | Status | Details | +|-------|--------|---------| +| 0 — Environment setup | ✅ / ❌ | ... | +| 1 — Clean build | ✅ / ❌ | ... | +| 2 — Preview server | ✅ / ❌ | ... | +| 3 — What's-new entry | ✅ / ❌ | ... | +| 4 — Version references | ✅ / ⚠️ / ❌ | ... | +| 5 — Integration docs | ✅ / ⚠️ / ❌ | ... | +| 6 — Smoke test | ✅ / ❌ | ... | +| 7 — Cleanup | ✅ / ❌ | ... | + +## Critical issues + +[Issues that must be fixed before release] + +### Issue N: [Title] + +**Phase:** N +**Severity:** Critical / High / Medium +**File:** [path with line number] +**Description:** ... +**Recommended fix:** ... + +## Warnings + +[Issues that should be reviewed but may be acceptable] + +## Stale version references + +| File | Line | Context | Classification | +|------|------|---------|---------------| +| ... | ... | ... | Stale / Intentional | + +## Integration docs status + +- Packages in catalog: N +- Mapped entries: N +- New mappings needed: [list] +- Stale mappings removed: [list] +- Unmapped packages: [list] + +## Passed checks + +[Brief list of everything that passed] +``` + +--- + +## Failure handling + +- **Build failure (Phase 1)**: This is a blocking failure. Log the error and continue with remaining phases to gather as much information as possible, but mark the overall verification as **FAILED**. +- **Missing what's-new file (Phase 3a)**: Critical failure. Document it and continue. +- **Stale version references (Phase 4)**: Flag each one with its classification. This is a **warning** unless the stale reference appears in user-facing installation or getting-started instructions, in which case it is **critical**. +- **Integration docs out of sync (Phase 5)**: Warning unless packages are completely unmapped. +- **Smoke test failures (Phase 6)**: Critical if pages fail to render; warning if only cosmetic issues. + +## Skills reference + +This agent depends on the following skills. Read the full skill instructions before using them: + +| Skill | File | When used | +|-------|------|-----------| +| doc-tester | `.github/skills/doc-tester/SKILL.md` | Phase 3 (content validation), Phase 6 (smoke test) | +| hex1b | `.github/skills/hex1b/SKILL.md` | Phase 2 (preview server management), terminal capture | +| playwright-cli | `.github/skills/playwright-cli/SKILL.md` | Phase 3d, Phase 6 (browser-based verification) | +| update-integrations | `.github/skills/update-integrations/SKILL.md` | Phase 5 (integration docs sync) | diff --git a/.github/policies/auto-merge.yml b/.github/policies/auto-merge.yml deleted file mode 100644 index 6ce2c8219..000000000 --- a/.github/policies/auto-merge.yml +++ /dev/null @@ -1,34 +0,0 @@ -id: -name: GitOps.PullRequestIssueManagement -description: GitOps.PullRequestIssueManagement primitive -owner: -resource: repository -disabled: false -where: -configuration: - resourceManagementConfiguration: - eventResponderTasks: - - description: Approve and auto-squash-merge bot PRs to main labeled 'auto-merge' - triggerOnOwnActions: true - if: - - payloadType: Pull_Request - - labelAdded: - label: ':octocat: auto-merge' - - targetsBranch: - branch: main - - or: - - isActivitySender: - user: dotnet-policy-service[bot] - then: - - enableAutoMerge: - mergeMethod: Squash - - approvePullRequest: - comment: "Approved; this PR will merge when all status checks pass." - - - description: Don't auto-merge PRs with 'auto-merge' label removed - if: - - payloadType: Pull_Request - - labelRemoved: - label: ':octocat: auto-merge' - then: - - disableAutoMerge \ No newline at end of file diff --git a/.github/prompts/documentation-coverage-audit.prompt.md b/.github/prompts/documentation-coverage-audit.prompt.md deleted file mode 100644 index b7c833cf6..000000000 --- a/.github/prompts/documentation-coverage-audit.prompt.md +++ /dev/null @@ -1,398 +0,0 @@ -# Documentation Coverage Audit Plan - -## Overview - -This plan provides a comprehensive methodology for auditing documentation coverage between the [dotnet/aspire](https://github.com/dotnet/aspire) source repository and the [aspire.dev](https://aspire.dev) documentation site. The goal is to identify gaps in documentation coverage and create actionable issues for Copilot or contributors to address. - -## Objectives - -1. **Catalog all APIs** in the dotnet/aspire repository -2. **Audit existing documentation** in microsoft/aspire.dev -3. **Identify deltas** between documented and undocumented features -4. **Generate issues** for each documentation gap - -## Phase 1: Source API Discovery - -### Step 1.1: Clone the dotnet/aspire repository - -```bash -git clone https://github.com/dotnet/aspire.git /tmp/aspire-source -cd /tmp/aspire-source -``` - -### Step 1.2: Identify all public API surfaces - -Scan the following namespace patterns in the dotnet/aspire repository: - -| Namespace Pattern | Description | Source Location | -|---|---|---| -| `Aspire.Hosting.*` | App host/orchestration APIs | `src/Aspire.Hosting.*/**/*.cs` | -| `Aspire.Components.*` | Client integration libraries | `src/Components/**/*.cs` | -| `Aspire.Dashboard.*` | Dashboard APIs | `src/Aspire.Dashboard/**/*.cs` | -| `Aspire.Cli.*` | CLI tooling | `src/Aspire.Cli/**/*.cs` | - -### Step 1.3: Extract public APIs - -For each project, identify: - -1. **Public classes** - All `public class` declarations -2. **Public interfaces** - All `public interface` declarations -3. **Extension methods** - All `public static` extension methods (especially `Add*` and `With*` patterns) -4. **Configuration options** - All classes ending in `Options` or `Settings` -5. **Resource types** - All classes implementing `IResource` or inheriting from resource base types - -### Step 1.4: Generate API inventory - -Create a structured inventory with the following format: - -```json -{ - "namespace": "Aspire.Hosting.Redis", - "package": "Aspire.Hosting.Redis", - "apis": [ - { - "name": "AddRedis", - "type": "extension_method", - "signature": "IResourceBuilder AddRedis(this IDistributedApplicationBuilder builder, string name, int? port = null)", - "file": "src/Aspire.Hosting.Redis/RedisBuilderExtensions.cs", - "line": 25, - "xmlDoc": "Adds a Redis container resource to the distributed application." - } - ] -} -``` - -## Phase 2: Documentation Audit - -### Step 2.1: Inventory existing documentation pages - -Scan the `src/frontend/src/content/docs/` directory and create a catalog of all documentation: - -```bash -find src/frontend/src/content/docs -name "*.mdx" -o -name "*.md" | sort -``` - -### Step 2.2: Categorize documentation by topic - -Map existing documentation to these categories: - -| Category | Directory | Description | -|---|---|---| -| Getting Started | `get-started/` | Onboarding and setup guides | -| Architecture | `architecture/` | Conceptual and design documentation | -| App Host | `app-host/` | Orchestration and hosting configuration | -| Fundamentals | `fundamentals/` | Core concepts and features | -| Integrations | `integrations/` | Database, messaging, caching, cloud integrations | -| Dashboard | `dashboard/` | Dashboard features and configuration | -| Testing | `testing/` | Testing patterns and libraries | -| Deployment | `deployment/` | Deployment guides and manifests | -| Diagnostics | `diagnostics/` | Logging, tracing, metrics | -| Extensibility | `extensibility/` | Custom resources and extensions | -| Reference | `reference/` | API reference and CLI documentation | - -### Step 2.3: Extract documented APIs - -For each documentation page, extract: - -1. **Package references** - NuGet packages mentioned -2. **API methods documented** - Extension methods, classes, interfaces covered -3. **Code samples** - APIs demonstrated in examples -4. **Configuration options** - Settings and options explained - -Use these patterns to identify API references: - -```regex -# Package references -\[📦\s*([^\]]+)\] -Aspire\.(Hosting|Components)\.[A-Za-z.]+ - -# Extension method calls -\.Add[A-Z][a-zA-Z]+\( -\.With[A-Z][a-zA-Z]+\( -builder\.[A-Z][a-zA-Z]+\( - -# Configuration classes -[A-Z][a-zA-Z]+Options -[A-Z][a-zA-Z]+Settings -``` - -### Step 2.4: Cross-reference with integration-docs.json - -Load `src/frontend/src/data/integration-docs.json` to understand the current package-to-documentation mapping: - -```javascript -const mappings = require('./src/frontend/src/data/integration-docs.json'); -// Each entry has { match: "Aspire.Package.Name", href: "/docs/path/" } -``` - -## Phase 3: Delta Analysis - -### Step 3.1: Compare API inventory to documentation - -For each API identified in Phase 1: - -1. Check if it's documented in any page from Phase 2 -2. Check if its package has a mapping in `integration-docs.json` -3. Classify as: - - **Documented** - API is covered with examples - - **Mentioned** - API is referenced but not fully explained - - **Missing** - API has no documentation - -### Step 3.2: Categorize documentation gaps - -Group gaps by severity and type: - -| Gap Type | Severity | Description | Example | -|---|---|---|---| -| Missing Integration Doc | High | No documentation page for a hosting package | `Aspire.Hosting.NewService` has no page | -| Missing Client Doc | High | No documentation for client/component package | `Aspire.NewService.Client` not documented | -| Missing API Reference | Medium | Public API not documented | `WithEnvironment()` method not explained | -| Incomplete Examples | Medium | Documentation exists but lacks code samples | Redis page missing clustering example | -| Missing Configuration | Low | Configuration options not documented | `RedisResourceOptions.Persistence` not explained | -| Outdated Content | Low | Documentation references deprecated APIs | Using old method signatures | - -### Step 3.3: Generate delta report - -Create a structured report: - -```json -{ - "summary": { - "total_apis": 450, - "documented_apis": 320, - "mentioned_apis": 80, - "missing_apis": 50, - "coverage_percentage": 71.1 - }, - "gaps": [ - { - "type": "missing_integration_doc", - "severity": "high", - "package": "Aspire.Hosting.NewDatabase", - "apis_affected": ["AddNewDatabase", "WithNewDatabaseConfiguration"], - "recommended_action": "Create new integration documentation page", - "suggested_location": "/integrations/databases/new-database/" - } - ] -} -``` - -## Phase 4: Issue Generation - -### Step 4.1: Issue template for documentation gaps - -Use this template for creating GitHub issues: - -```markdown ---- -title: "[Docs] Document {API/Feature Name}" -labels: documentation, help-wanted, good-first-issue -assignees: '' ---- - -## Summary - -{Brief description of what needs to be documented} - -## API/Feature Details - -- **Package**: `{NuGet package name}` -- **Namespace**: `{.NET namespace}` -- **Type**: {Integration/Feature/API Reference} -- **Source**: [{Link to source file}]({GitHub URL}) - -## Documentation Requirements - -- [ ] Overview of the feature/API -- [ ] Installation/setup instructions -- [ ] Basic usage example -- [ ] Configuration options -- [ ] Advanced scenarios (if applicable) -- [ ] Troubleshooting tips - -## Suggested Location - -`src/frontend/src/content/docs/{suggested/path}/` - -## Related Documentation - -- {Links to related existing docs} - -## Reference Materials - -- Source code: {link} -- XML documentation: {extracted XML docs} -- Related issues: {links} - -## Acceptance Criteria - -- [ ] Documentation follows [contributor guide](https://aspire.dev/community/contributor-guide/) style -- [ ] Code samples are tested and working -- [ ] All public APIs in the package are documented -- [ ] Page is added to sidebar navigation -- [ ] Links added to integration-docs.json mapping -``` - -### Step 4.2: Prioritization criteria - -Prioritize issues based on: - -1. **Usage frequency** - APIs with high download counts get priority -2. **Community requests** - Features mentioned in discussions/issues -3. **Complexity** - Simple APIs can be quick wins -4. **Dependencies** - Document foundational APIs before advanced features - -### Step 4.3: Batch issue creation - -Group related gaps into logical issues: - -- One issue per integration package -- One issue per major feature area -- Separate issues for API reference vs. conceptual docs - -## Phase 5: Execution Workflow - -### For LLM/Agent execution - -#### Step 5.1: API Discovery Script - -```bash -#!/bin/bash -# Run from dotnet/aspire repository root - -# Find all public API surface -find src -name "*.cs" -exec grep -l "public class\|public interface\|public static" {} \; > /tmp/api-files.txt - -# Extract extension methods -grep -rh "public static.*this I.*Builder" src/ --include="*.cs" > /tmp/extension-methods.txt - -# Extract resource types -grep -rh "class.*Resource\|interface.*Resource" src/ --include="*.cs" > /tmp/resource-types.txt -``` - -#### Step 5.2: Documentation inventory script - -```bash -#!/bin/bash -# Run from microsoft/aspire.dev repository root - -# List all documentation pages -find src/frontend/src/content/docs -name "*.mdx" -o -name "*.md" > /tmp/doc-pages.txt - -# Extract package references from docs -grep -rh "Aspire\.\(Hosting\|Components\)\.[A-Za-z.]*" src/frontend/src/content/docs/ > /tmp/doc-packages.txt - -# Count API mentions -grep -roh "\.Add[A-Z][a-zA-Z]*\|\.With[A-Z][a-zA-Z]*" src/frontend/src/content/docs/ | sort | uniq -c | sort -rn > /tmp/api-mentions.txt -``` - -#### Step 5.3: Comparison workflow - -1. Load API inventory from dotnet/aspire -2. Load documentation inventory from aspire.dev -3. For each API: - - Search all documentation files for mentions - - Check integration-docs.json for package mapping - - Classify coverage level -4. Generate delta report -5. Create prioritized issue list - -## Appendix A: Package Categories - -### Hosting packages (App Host) - -These packages provide resource builders for the app host: - -| Package | Category | Expected Doc Location | -|---|---|---| -| `Aspire.Hosting.Redis` | Caching | `/integrations/caching/redis/` | -| `Aspire.Hosting.PostgreSQL` | Databases | `/integrations/databases/postgres/` | -| `Aspire.Hosting.RabbitMQ` | Messaging | `/integrations/messaging/rabbitmq/` | -| `Aspire.Hosting.Azure.*` | Cloud | `/integrations/cloud/azure/` | -| `Aspire.Hosting.AWS.*` | Cloud | External AWS docs | - -### Client packages (Components) - -These packages provide client integrations: - -| Package | Category | Expected Doc Location | -|---|---|---| -| `Aspire.StackExchange.Redis` | Caching | `/integrations/caching/redis/` | -| `Aspire.Npgsql` | Databases | `/integrations/databases/postgres/` | -| `Aspire.RabbitMQ.Client` | Messaging | `/integrations/messaging/rabbitmq/` | -| `Aspire.Azure.*` | Cloud | `/integrations/cloud/azure/` | - -## Appendix B: Documentation Quality Checklist - -For each documented API, verify: - -- [ ] Clear description of purpose -- [ ] Installation instructions (NuGet package reference) -- [ ] Basic usage example with working code -- [ ] All public methods documented -- [ ] Configuration options explained -- [ ] Common use cases covered -- [ ] Error handling guidance -- [ ] Links to related documentation -- [ ] Follows aspire.dev style guide - -## Appendix C: Known Documentation Gaps (Initial Assessment) - -Based on initial repository analysis, these areas likely need attention: - -### High Priority - -1. **Extensibility** - Limited documentation on creating custom resources -2. **Advanced Networking** - Service discovery internals, custom endpoints -3. **Deployment Targets** - Non-Azure deployment scenarios -4. **Testing Patterns** - Integration testing best practices - -### Medium Priority - -1. **Configuration Deep Dives** - Advanced configuration scenarios -2. **Performance Tuning** - Resource limits, scaling guidance -3. **Security** - Authentication, authorization patterns -4. **Observability** - Custom telemetry, dashboard customization - -### Community Toolkit - -1. **CommunityToolkit.Aspire.\*** packages need documentation mapping -2. Many community integrations have limited documentation - -## Appendix D: Automation Opportunities - -### Automated documentation checks - -1. **CI Pipeline** - Validate all packages have documentation mappings -2. **Link Checker** - Ensure integration-docs.json links are valid -3. **API Drift Detection** - Alert when new APIs are added without docs -4. **Coverage Metrics** - Track documentation coverage over time - -### Script templates - -```javascript -// Check for undocumented packages -const integrations = require('./src/frontend/src/data/aspire-integration-names.json'); -const docMappings = require('./src/frontend/src/data/integration-docs.json'); - -const mappedPackages = new Set(docMappings.map(d => d.match)); -const undocumented = integrations.filter(pkg => !mappedPackages.has(pkg)); - -console.log('Undocumented packages:', undocumented); -``` - -## Next Steps - -1. **Run Phase 1** - Clone dotnet/aspire and generate API inventory -2. **Run Phase 2** - Audit existing aspire.dev documentation -3. **Run Phase 3** - Generate delta report -4. **Run Phase 4** - Create GitHub issues for gaps -5. **Assign to Copilot** - Use labels to enable Copilot assignment -6. **Track Progress** - Monitor issue resolution and coverage metrics - -## Success Metrics - -- Documentation coverage > 90% of public APIs -- All integration packages have dedicated documentation pages -- All packages mapped in integration-docs.json -- Community feedback indicates documentation is comprehensive diff --git a/.github/prompts/migrate-from-learn.prompt.md b/.github/prompts/migrate-from-learn.prompt.md deleted file mode 100644 index 1b970ddca..000000000 --- a/.github/prompts/migrate-from-learn.prompt.md +++ /dev/null @@ -1,225 +0,0 @@ -# Documentation Migration Plan: docs-aspire to aspire.dev - -## Overview - -Migrate documentation content from the legacy `E:\GitHub\docs-aspire` repository to the new `aspire.dev` site, transforming content from docfx/Microsoft Learn format to Astro/Starlight format. - -## Source Repository Details - -- **Location**: `E:\GitHub\docs-aspire` -- **Format**: YAML frontmatter + Markdown (`.md`) -- **Build system**: docfx (Microsoft Learn) -- **Structure**: Uses snippet directories for code samples -- **Target platform**: Microsoft Learn documentation - -## Target Repository Details - -- **Location**: Current workspace (`E:\GitHub\aspire.dev`) -- **Format**: Frontmatter + MDX (`.mdx`) -- **Build system**: Astro + Starlight -- **Structure**: Inline code samples, custom components -- **Target platform**: aspire.dev website - -## Key Differences & Transformations - -### Format Changes -- **File extension**: `.md` → `.mdx` -- **Code samples**: External snippets → Inline code blocks -- **Frontmatter**: YAML structure differences (need to map fields) -- **Components**: Microsoft Learn includes → Astro/Starlight components -- **Images**: Copy from `docs-aspire/docs/{section}/media/` to `aspire.dev/src/frontend/src/assets/{section}/` -- **Excalidraw sources**: Always copy `.excalidraw` files along with image exports - -### Frontmatter Transformation -- **Remove**: `ms.date`, `ms.topic`, `ms.custom`, and other Microsoft Learn-specific metadata -- **Keep**: `title`, `description` -- **Add if needed**: `tableOfContents`, `lastUpdated` -- **Simplify titles**: Remove redundant "Aspire" prefix when appropriate (e.g., "Aspire testing overview" → "Testing overview") - -### Component Mapping -- **Admonitions**: `> [!NOTE]` → `