Clarify third-party link guidelines

[IEvangelist]

Summary

• Establish clear relevance, neutrality, and non-promotion standards for third-party links.
• Allow necessary prerequisite, cost-planning, attribution, acknowledgment, and generated-catalog uses.
• Require affiliation disclosure and add a pull request template section where contributors can provide it.

Third-party links and affiliations

None. This pull request doesn't add or change third-party links.

Validation

• pnpm --dir ./src/frontend run test:unit:docs
• Prettier check for .github/PULL_REQUEST_TEMPLATE.md
• git diff --check

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1399. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[Copilot]

Pull request overview

This PR updates the contributor guide to add explicit editorial guidelines for including third-party links in aspire.dev documentation, aiming to keep links relevant, neutral, and non-promotional while adding an affiliation disclosure expectation.

Changes:

• Adds a new “Third-party links” section to the writing style guide.
• Defines criteria for when third-party links are appropriate, how to frame them, and what types of destinations to avoid.
• Requires contributors to disclose material affiliations in the PR.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adamint]

I'm in favor of writing this down — we've needed it. My concern is that as worded, the policy makes a fair amount of our existing content a violation, and I'd rather we fix that now than have the first person who cites this rule get pointed at our own pages.

Concretely, on main today:

• get-started/deploy-first-app.mdx:110 links to https://www.docker.com/products/docker-desktop — a product page.
• get-started/deploy-first-app.mdx:119 links to https://azure.microsoft.com/free/ — about as lead-gen as a link gets.
• integrations/cloud/azure/configure-container-apps.mdx:444 links "Container Apps pricing" to the billing docs.
• community/thanks.mdx:214 and :429 read "The world's most advanced open-source relational database" and "The most widely deployed open-source message broker" — those are vendor marketing lines.

All four are, I think, good content. Prerequisites have to link to the thing you install, cost planning has to link to pricing, and the thanks page is inherently promotional by design. So the rule needs a carve-out rather than those pages needing edits.

I'd suggest something like: prerequisite download/signup pages, pricing references needed for cost planning, and attribution pages are fine; the rule targets links whose primary purpose is promotion.

Two more things I'd tighten:

"not exclusively to a paid product, pricing, lead-generation, or sales page" — "exclusively" is a loophole. Any sales page with a paragraph of technical content stops being "exclusive," and the argument is unfalsifiable. Splitting it into a positive rule and a flat prohibition reads better: "Link to technical documentation or other substantive resources. Do not link to paid products, pricing, lead-generation, or sales pages" — combined with the carve-out above.

"competes with Aspire" — I genuinely don't know how to apply this, and I think that's a problem for a rule contributors are supposed to self-enforce. Dapr is a documented integration (dev-containers.mdx:242) and also overlaps with our building blocks. Docker Compose and Kubernetes are both deployment targets and alternative orchestrators. LocalVsProdEnvironments.astro:50-101 presents AWS and Azure as production targets. If "competes" is meant to catch "here's a better alternative to Aspire" content, saying that directly would be clearer than asking people to judge competitive overlap.

Two smaller notes:

• The new bullets drop the bolded lead-in pattern the rest of that section uses (- **Follow formatting conventions** - …). Worth matching for consistency.
• The affiliation-disclosure rule asks contributors to disclose "in the pull request," but this repo has no .github/pull_request_template.md, so there's no prompt and nowhere it's captured. A template with that field would make the rule actually operate. Related: a lot of third-party content arrives through automation rather than human PRs — update-integration-data.yml opens bot PRs, update-integrations.ts:288 copies NuGet package descriptions verbatim, and update-samples.ts pulls READMEs from aspire-samples. Worth saying whether generated catalogs are exempt or whether the reviewing maintainer carries the same standard.

Rendering is fine, for what it's worth — I built the site and checked. The ### Third-party links H3 lands in the right place under the writing-style H2, gets id="third-party-links", shows up in the on-this-page TOC (the page frontmatter sets H2–H3 depth), the anchor scrolls correctly, it wraps cleanly at 375px, and lint, link validation, the forbidden-words gate, and 267 unit tests all pass.

Not blocking on any of this if you'd rather land it and iterate — but I think the prerequisite/pricing carve-out is worth doing before merge, since without it the guide contradicts our own getting-started page.

[IEvangelist]

Thanks @adamint — this was helpful.

the policy makes a fair amount of our existing content a violation

While I do not agree with that statement, I revised the policy to add explicit exceptions for prerequisite, cost-planning, and attribution content; focus the restriction on promotional intent instead of competitive overlap; clarify how generated catalogs are reviewed; match the existing bold lead-in style; and add a PR template section for link and affiliation disclosures.

[JamesNK]

Summary

Reviewed PR head 49c0315e564d062f5248bb2e64a96418133df273 against aspire.dev base main (68f615ad3692b7ae110e28abb1337eda5dda3acd). No Aspire product source repository was needed because this PR adds editorial policy rather than product/API claims.

Phase A catalog: 8 added policy statements — 7 narrative rules and 1 repository-contract claim. The non-narrative claim is verified; 0 contradicted, 0 unverifiable, 0 verified-with-nuance.

Phase B exercised /community/contributor-guide/#third-party-links at desktop and 375px mobile width: 0 critical issues, 0 warnings.

Phase A — Claim verification

Verified claims and evidence

• Verified: The contributor guide directs authors to disclose affiliations in the Third-party links and affiliations section of the PR description. .github/PULL_REQUEST_TEMPLATE.md creates that exact section and prompts contributors to list changed third-party links, disclose employment/sponsorship/ownership, or write “None.”
• Narrative policy rules: relevance, neutrality, non-promotion, substantive destinations, necessary exceptions, affiliation treatment, and generated-content review are editorial requirements rather than Aspire runtime claims.
• The final exception text covers the existing prerequisite, cost-planning, attribution, and generated-catalog cases raised in the earlier review.

Phase B — Documentation Test Report

Focus Area: Contributor guide — Third-party links
Date: 2026-07-31
Tester: doc-tester agent

Category	Passed	Failed	Warnings
Content Accuracy	3	0	0
Code Examples	0	0	0
CLI Commands	0	0	0
Links	3	0	0

Critical Issues

None.

Warnings

None.

Passed Checks

• The changed route loads with the expected page title.
• The Third-party links heading renders with id="third-party-links" and is exposed through page navigation and an accessible section permalink.
• All seven policy bullets render in the intended order with the expected text.
• Clicking the section permalink scrolls the heading into view.
• At 375px, document width equals viewport width; no horizontal overflow was detected.
• The section contains no new external links requiring destination validation.

Recommendations

1. Priority fixes: None.
2. Documentation gaps: None in the changed section.
3. Product issues: None.

Knowledge gaps

None.