diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..28b77bcf4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +## Summary + + + +## Third-party links and affiliations + + + +## Validation + + diff --git a/src/frontend/src/content/docs/community/contributor-guide.mdx b/src/frontend/src/content/docs/community/contributor-guide.mdx index cadc81def..7dadb7986 100644 --- a/src/frontend/src/content/docs/community/contributor-guide.mdx +++ b/src/frontend/src/content/docs/community/contributor-guide.mdx @@ -235,6 +235,18 @@ When contributing to `aspire.dev`, follow these writing guidelines to ensure con - **Follow formatting conventions** - Use consistent formatting for code snippets, commands, and technical terms. Refer to the examples in this guide for guidance. - **Review existing content** - Before adding new content, review existing documentation to avoid duplication and ensure coherence. +### Third-party links + +Third-party links are appropriate when they help readers complete a task or understand a topic. Apply these standards to both authored and generated content: + +- **Use links sparingly** - Include third-party links only when they're directly relevant. Prefer Aspire documentation when it covers the same information. +- **Present resources neutrally** - Describe third-party resources factually. Avoid endorsements, marketing claims, promotional comparisons, and calls to purchase or sign up. +- **Avoid promotion** - Don't add links or surrounding content whose primary purpose is to market a third-party offering or position it as a preferred replacement for Aspire. +- **Choose substantive destinations** - Link to technical documentation or other substantive resources. Don't link to product, pricing, lead-generation, or sales pages except as described in the following exceptions. +- **Allow necessary exceptions** - Prerequisite download or account sign-up pages, pricing or billing references needed for cost planning, and project descriptions or links on attribution and acknowledgment pages are allowed. Keep each exception limited to the context that makes it necessary. +- **Disclose affiliations** - In the **Third-party links and affiliations** section of the pull request description, disclose any material affiliation with a linked organization, such as employment, sponsorship, or ownership. An affiliation doesn't automatically disqualify a link, but the link and surrounding content must meet the same editorial standards as any other contribution. +- **Review generated content** - Automated updates and generated catalogs aren't exempt. They may reproduce upstream metadata when that's the catalog's explicit purpose, but the reviewing maintainer must apply the same editorial standards to the surrounding content and linked destinations. + ### AppHost-specific C# and TypeScript content When you are documenting AppHost-specific content that changes between C# and TypeScript, use synced `Tabs` and `TabItem` blocks with `syncKey='aspire-lang'`. Each code snippet should have its own C# and TypeScript selector, and the shared sync key keeps the selected language consistent across the page.