Sync public contributor guide with current internal guidance - #1191
Sync public contributor guide with current internal guidance#1191M. Baldwin (msmbaldwin) wants to merge 2 commits into
Conversation
Factual/procedural updates aligning the public contributor guide with the authoritative internal guide (docs-help-pr): - Links: add FWLinks/aka.ms guidance (don't use in Learn content). - Metadata: add ms.topic and ms.service to required attributes. - GitHub issues & feedback: update feedback control names to "This page" / "This product". - Process a pull request: merge method is repository-specific (#sign-off vs. Squash and merge). - Create a pull request / Make major changes: note the release-branch exception when the base branch isn't main; fix PR-title default wording. - Learn Authoring Pack: add Learn Scaffolding and Cleanup scripts to the bundled extensions. - Install content-authoring tools: link to new AI-assisted authoring tools. New articles ported from internal guidance (external-appropriate): - Contributor License Agreement (CLA) flow for community contributors. - Accessibility and alt text. - Add images and screenshots (incl. secure screenshots). - AI-assisted authoring tools (Learn Authoring Assistant, GitHub Copilot). TOC updated for the new articles; ms.date refreshed on edited files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 902b5092-7ab8-4365-8259-7dbbb99c3bc4
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
…late
- Revert the FWLinks/aka.ms section in the links article: external
contributors can't create ShortLinks, so that guidance is internal-only
and out of scope for the public guide. (Restores the file to its
original state, including ms.date.)
- Fix an unintended edit to metadata.md where the required-attributes date
bump also overwrote the Learn Article Templates dynamic placeholder
"ms.date: {@Date}". Restored the placeholder; the auto-populate behavior
is unchanged.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 902b5092-7ab8-4365-8259-7dbbb99c3bc4
|
Learn Build status updates of commit 81006a8:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| Contribute/content/accessibility.md | View | Details | |
| Contribute/content/add-images.md | View | Details | |
| Contribute/content/ai-authoring-tools.md | View | Details | |
| Contribute/content/contributor-license-agreement.md | View | Details | |
| Contribute/content/how-to-write-docs-auth-pack.md | 💡Suggestion | View | Details |
| Contribute/content/metadata.md | 💡Suggestion | View | Details |
| Contribute/content/create-pull-request.md | ✅Succeeded | View | |
| Contribute/content/get-started-setup-tools.md | ✅Succeeded | View | |
| Contribute/content/how-to-create-github-issues.md | ✅Succeeded | View | |
| Contribute/content/how-to-write-major-edits.md | ✅Succeeded | View | |
| Contribute/content/process-pull-request.md | ✅Succeeded | View | |
| Contribute/content/provide-feedback.md | ✅Succeeded | View | |
| Contribute/content/TOC.yml | ✅Succeeded | View |
Contribute/content/accessibility.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'cahublou' is not a valid GitHub ID.
Contribute/content/add-images.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'cahublou' is not a valid GitHub ID.
Contribute/content/ai-authoring-tools.md
- Line 7, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'cahublou' is not a valid GitHub ID.
Contribute/content/contributor-license-agreement.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'cahublou' is not a valid GitHub ID.
Contribute/content/how-to-write-docs-auth-pack.md
- Line 8, Column 12: [Suggestion: ms-author-invalid - See documentation]
Invalid value for 'ms.author', 'mbradley' is not a valid Microsoft alias.
Contribute/content/metadata.md
- Line 5, Column 12: [Suggestion: ms-author-invalid - See documentation]
Invalid value for 'ms.author', 'sabarret' is not a valid Microsoft alias.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
Summary
This PR brings the public contributor guide back in sync with the current authoritative internal guidance, and ports over a few externally-relevant topics that were missing. All changes are factual/procedural — public tone and structure are preserved. Opened as a draft for review.
Factual/procedural fixes to existing articles
how-to-write-links.md/p/only as external last resort).metadata.mdms.topicandms.serviceto the required metadata attributes (were missing).how-to-create-github-issues.md,provide-feedback.mdprocess-pull-request.md#sign-offvs. Squash and merge), not universal.create-pull-request.mdhow-to-write-major-edits.mdmain.how-to-write-docs-auth-pack.mdget-started-setup-tools.mdNew articles (ported from internal guidance, made external-appropriate)
contributor-license-agreement.md) — the CLA flow for community contributors, incl. the@microsoft-github-policy-servicebot commands.accessibility.md) — meaningful alt text, accessible tables/links, and build validation.add-images.md) — image syntax, storage/naming, compression, alt text, and secure screenshots (scrub PII).ai-authoring-tools.md) — optional Learn Authoring Assistant and GitHub Copilot, alongside the Learn Authoring Pack.TOC.ymlupdated for the new articles;ms.daterefreshed on edited files.Notes for reviewers
dev_langscoverage).