Refactor guidelines artifacts - #48
Merged
Kristen Womack (kristenwomack) merged 6 commits intoSep 2, 2026
Merged
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Kristen Womack (kristenwomack)
requested a review
from Shayne Boyer (spboyer)
as a code owner
August 21, 2026 23:25
Kristen Womack (kristenwomack)
requested review from
Arun Sekhar (achandmsft)
and removed request for
Shayne Boyer (spboyer)
August 21, 2026 23:26
Copilot started reviewing on behalf of
Arun Sekhar (achandmsft)
September 1, 2026 00:44
View session
Marina He (hemarina)
suggested changes
Sep 1, 2026
Marina He (hemarina)
left a comment
Marina He (hemarina)
left a comment
There was a problem hiding this comment.
Thanks for the comprehensive refactor. The separation between core azd requirements, Awesome AZD publication requirements, and optional repository enhancements makes the guidance easier to navigate. I found two documentation compatibility issues that should be addressed before merging.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refreshes and restructures the template-authoring guidance in this repo to better reflect current azd expectations, separate core template requirements from Awesome AZD publication requirements, and provide copyable assets for template authors (per #47).
Changes:
- Replaces the root README with a navigation-focused entry point and explicit “requirement layers” model.
- Adds a reusable, copy/paste template
README.mdand modernizes guidance across publishing, troubleshooting, configuration, and ops. - Updates language-specific structure guidance (C#, Java, JS/TS, Python) to be adaptable rather than prescriptive, and refreshes contributor-facing templates.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| SECURITY.md | Simplifies MSRC reporting language. |
| README.md | New repo entry point + navigation + requirement layers. |
| publishing-guidelines.md | Reframes publishing guidance around core readiness vs Awesome AZD readiness. |
| docs/template-readme.md | Adds reusable template README authors can copy. |
| docs/structure-samples/structure-samples.md | New overview for language structure samples. |
| docs/structure-samples/python/python.md | Modernizes Python guidance (pyproject, runtime policy, testing, identity, observability). |
| docs/structure-samples/javascript/javascript.md | Modernizes JS/TS guidance (runtime policy, package managers, testing, identity, observability). |
| docs/structure-samples/java/java.md | Expands Java guidance (Maven/Gradle layouts, runtime, deps, testing, observability). |
| docs/structure-samples/csharp/csharp.md | Expands C#/.NET guidance (layout, runtime, deps, testing, observability). |
| docs/readme.md | Establishes normative language + guidance map + requirement layers. |
| docs/next-steps/next-steps-ai-starter.md | Replaces starter follow-up doc with a more durable checklist + current links. |
| docs/development-guidelines/trouble-shooting.md | Rewrites troubleshooting into a staged diagnostic workflow + Foundry references. |
| docs/development-guidelines/template-configuration.md | Expands azure.yaml/hooks portability guidance + optional CI/devcontainer guidance. |
| docs/development-guidelines/recommended-practices-per-domain.md | Replaces minimal list with comprehensive cross-domain recommendations using MUST/SHOULD/MAY. |
| docs/development-guidelines/operational-guidelines.md | Replaces long-form process content with concise governance/ownership guidance. |
| docs/development-guidelines/global-deployment.md | Reframes as Foundry deployment-type selection guidance (keeps filename for stability). |
| docs/development-guidelines/development-process.md | Updates contribution flow guidance to GitHub flow + rulesets. |
| docs/development-guidelines/definition-of-done.md | Rewrites DoD into MUST/SHOULD/MAY checklist with Awesome AZD scoping. |
| CONTRIBUTING.md | Updates contributing guidance and reinforces normative language usage. |
| .github/PULL_REQUEST_TEMPLATE.md | Simplifies PR template and adds validation checklist aligned to new guidance. |
| .github/ISSUE_TEMPLATE.md | Replaces issue template content with a guidance-focused template (see review note). |
| .github/CODEOWNERS | Updates CODEOWNERS list. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Arun Sekhar (achandmsft)
previously requested changes
Sep 1, 2026
Arun Sekhar (achandmsft)
left a comment
Arun Sekhar (achandmsft)
left a comment
There was a problem hiding this comment.
Kristen Womack (@kristenwomack) , Ran Copilot review (so please look at copilot comments as well). Also added a couple of comments from my manual review adding on to Copilot and Marina's review. Please take a look.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Kristen Womack (kristenwomack)
requested review from
Arun Sekhar (achandmsft) and
Marina He (hemarina)
September 1, 2026 16:43
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 32566aab-8ba1-440d-a00a-4098aebf4772
Marina He (hemarina)
approved these changes
Sep 1, 2026
Marina He (hemarina)
left a comment
Marina He (hemarina)
left a comment
There was a problem hiding this comment.
LGTM. Just this one note
Address review feedback: when validatePaths includes README.md, the template-validation-action replaces the default heading check with the README_H2_TAG environment variable. Without it set explicitly, a README missing all required headings passes validation. Add README_H2_TAG to the example so it stays consistent with the heading requirement above. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 32566aab-8ba1-440d-a00a-4098aebf4772
Kristen Womack (kristenwomack)
requested a review
from Arun Sekhar (achandmsft)
September 2, 2026 03:33
Marina He (hemarina)
approved these changes
Sep 2, 2026
Arun Sekhar (achandmsft)
left a comment
Arun Sekhar (achandmsft)
left a comment
There was a problem hiding this comment.
Looks good, thanks Kristen Womack (@kristenwomack)
Kristen Womack (kristenwomack)
merged commit Sep 2, 2026
22de603
into
Azure-Samples:main
1 check passed
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Refactors guidelines to bring in most current recommendations and requirements. Closes #47