From fdf2c83cca07cbd1e63886b1f2f2509a94b88053 Mon Sep 17 00:00:00 2001 From: "well-architected-sync-bot[bot]" <235114805+well-architected-sync-bot[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 22:55:12 +0000 Subject: [PATCH] Sync from github/github-well-architected-internal (main) Source Repository: github/github-well-architected-internal Source Branch: main Source SHA: ea7fb1f61daf4b556f92335bc2cdd3a86ffa6e14 --- CONTRIBUTING.md | 50 ++++++++++++++++++++++++++++++++-------------- docs/taxonomies.md | 44 ++++++++++++++++++++++++++++++++-------- 2 files changed, 71 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index add56eb..974cbc1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,14 +66,14 @@ flowchart LR F --> H[[Step 7
GitHub Review]] H --> I[Step 8
Publish] - style A fill:pink - style B fill:pink - style C fill:pink - style D fill:pink - style E fill:yellow - style F fill:pink - style H fill:silver - style I fill:yellow + style A fill:pink,color:#000 + style B fill:pink,color:#000 + style C fill:pink,color:#000 + style D fill:pink,color:#000 + style E fill:yellow,color:#000 + style F fill:pink,color:#000 + style H fill:silver,color:#000 + style I fill:yellow,color:#000 ``` **Legend:** @@ -342,19 +342,18 @@ There are several primary types of contributions to this project: ### 📝 Content Library Article Submission(s) -Contributions will typically author content articles. To start writing, we recommend review these essential framework resources: +Contributions will typically author content articles under `/content/` folder. To start writing, we recommend reviewing these essential framework resources: - [Framework Overview] - Learn about the WAF mission, vision, objectives, and five pillars -- [Project Structure](/docs/project-structure.md) - Understand the repository layout and where content lives - [Taxonomies](/docs/taxonomies.md) - Explore the design principles, areas, and other classifications **Inspiration for Content Library articles** comes from **Azure Architecture Center**. See the following example articles for your inspiration: 💡 -- [📄 Reliability: Recommendations for designing for redundancy](https://learn.microsoft.com/en-us/azure/well-architected/reliability/redundancy) -- [📄 Security: Recommendations for identity and access management](https://learn.microsoft.com/en-us/azure/well-architected/security/identity-access) -- [📄 Cost Optimization: Recommendations for optimizing environment costs](https://learn.microsoft.com/en-us/azure/well-architected/cost-optimization/optimize-environment-costs) -- [📄 Operational Excellence: Recommendations for using infrastructure as code](https://learn.microsoft.com/en-us/azure/well-architected/operational-excellence/infrastructure-as-code-design) -- [📄 Performance Efficiency: Recommendations for capacity planning](https://learn.microsoft.com/en-us/azure/well-architected/performance-efficiency/capacity-planning) +- [📄 Reliability: Recommendations for designing for redundancy][reliability-redundancy] +- [📄 Security: Recommendations for identity and access management][security-identity-access] +- [📄 Cost Optimization: Recommendations for optimizing environment costs][cost-optimize-environment] +- [📄 Operational Excellence: Recommendations for using infrastructure as code][operational-iac] +- [📄 Performance Efficiency: Recommendations for capacity planning][performance-capacity-planning] ### 💻 Website Code Changes @@ -412,6 +411,22 @@ See [Framework Overview] for details on each pillar. - Keep sentences **short and clear** - Avoid unnecessary jargon - Include practical examples +- Prefer GitHub Docs links to **Enterprise Cloud**: `https://docs.github.com/en/enterprise-cloud@latest` (unless the guidance is specific to GitHub Enterprise Server) +- Use Hugo shortcodes to keep articles consistent (see `archetypes/default.md`): + - Further assistance: `{{% seeking-further-assistance-details %}}` + - Related links: `{{% related-links-github-docs %}}` + +### Callouts + +Use Hextra callouts to highlight important information: + +```md +{{< callout type="info" >}} +This is an informational note. +{{< /callout >}} +``` + +Use `type` for standard callouts (`info`, `warning`, `error`). For custom callouts, use `emoji`. > [!IMPORTANT] > Remember: [GitHub Docs] is the primary source of truth. Our framework supplements documentation with design thinking and decision-making guidance. @@ -483,3 +498,8 @@ By contributing, you agree that your contributions will be licensed under the [M [Framework Overview]: /docs/framework-overview.md [Create a content request Issue]: https://github.com/github/github-well-architected-internal/issues/new?template=request-content.yml [GitHub Docs]: https://docs.github.com +[reliability-redundancy]: https://learn.microsoft.com/en-us/azure/well-architected/reliability/redundancy +[security-identity-access]: https://learn.microsoft.com/en-us/azure/well-architected/security/identity-access +[cost-optimize-environment]: https://learn.microsoft.com/en-us/azure/well-architected/cost-optimization/optimize-environment-costs +[operational-iac]: https://learn.microsoft.com/en-us/azure/well-architected/operational-excellence/infrastructure-as-code-design +[performance-capacity-planning]: https://learn.microsoft.com/en-us/azure/well-architected/performance-efficiency/capacity-planning diff --git a/docs/taxonomies.md b/docs/taxonomies.md index abbaf6b..86558b4 100644 --- a/docs/taxonomies.md +++ b/docs/taxonomies.md @@ -14,7 +14,7 @@ When creating a new Content Library article, include relevant taxonomies in the --- title: 'Your Article Title' draft: false -publishDate: 2024-12-05 +publishDate: 2025-12-05 params: author: @@ -43,7 +43,7 @@ features: components: - code-scanning - - repository-rulesets + - branch-rulesets --- ``` @@ -65,10 +65,12 @@ pillars: # The areas of the GitHub adoption journey. Inspiration taken from docs.github.com areas: + - agent-and-extensions - ci-cd-and-devops - client-apps - collaborative-coding - community + - context-engineering - developers - enterprise-and-teams - getting-started @@ -78,13 +80,16 @@ areas: # Classifications of industries who may be at different stages of the customer journey. verticals: - automotive - - manufacturing - finance - gaming - - media - government - information-technology + - manufacturing + - media + - professional-service + - retail - smb-corporate + - mid-market # Individuals in key roles on the customer journey, typically consisting of one or more administrators and the end-user community. personas: @@ -105,43 +110,65 @@ platform: features: - codespaces - copilot + - copilot-cli - git - - github-advanced-security - github-actions + - github-advanced-security + - github-apps - github-cli + - github-desktop + - github-discussions - github-mobile + - github-marketplace - github-pages + - github-packages - github-projects + - github-releases - issues-and-pull-requests - - mcp - repositories # Deeper-level topics of the GitHub Platform and its features. They are most often interacted with by end-users. components: - audit-log - actions-oidc + - actions-runners - billing-and-cost-centers + - branch-rulesets + - caches-and-artifacts + - chatmode - coding-agents - code-review-automation - code-scanning + - context-engineering - copilot-autofix - - copilot-enterprise - copilot-business - copilot-chat + - copilot-enterprise + - copilot-spaces + - custom-instructions - dependabot-and-dependency-review + - deployment-and-environments - git-lfs - governance-and-policy + - graph-api - insights-and-metrics - limits + - mcp-and-extensions + - migration - performance-engineering + - prompt-engineering - push-rulesets - repository-custom-properties - - repository-rulesets + - repository-rulesets # to be deprecated + - rest-api + - review-agents + - secret-protection - secret-scanning - security-campaigns - security-configurations - sso-saml - sso-oidc + - webhooks # Associated teams and other GitHub and Partner resources that can provide additional support. github: @@ -153,6 +180,7 @@ github: - enterprise-support - expert-services - fast-track + - microsoft - partners - product-marketing ```