Sync public contributor guide with current internal guidance

Contribute/content/TOC.yml

@@ -18,6 +18,8 @@
           href: create-pull-request.md
     - name: Process a pull request
       href: process-pull-request.md
+    - name: Contributor License Agreement
+      href: contributor-license-agreement.md
     - name: Git and GitHub fundamentals
       href: git-github-fundamentals.md
     - name: Write for Hacktoberfest
@@ -53,6 +55,12 @@
     - name: Add code to articles
       href: code-in-docs.md
       displayName: backtick, code blocks, inline code blocks, repo snippet reference, !code-, interactive code snippets, programming languages, languages, code extensions, extensions
+    - name: Add images and screenshots
+      href: add-images.md
+      displayName: images, screenshots, media, alt text, compression, secure screenshots
+    - name: Accessibility and alt text
+      href: accessibility.md
+      displayName: accessibility, alt text, alternative text, accessible tables, link text, contrast, color
     - name: Format text
       href: text-formatting-guidelines.md
       displayName: text formatting, bold, italics, code style, code blocks, inline code, placeholders, headings, link text, keys, keyboard shortcuts, shortcuts
@@ -85,6 +93,9 @@
           href: docs-authoring/sort-selection.md
         - name: Jupyter notebooks
           href: docs-authoring/jupyter-notebooks.md
+    - name: AI-assisted authoring tools
+      href: ai-authoring-tools.md
+      displayName: AI, Copilot, GitHub Copilot, Learn Authoring Assistant, authoring assistant
 - name: Documentation set-specific guidance
   items:
       - name: .NET docs

Contribute/content/accessibility.md

@@ -0,0 +1,87 @@
+---
+title: Accessibility and alt text
+description: Learn how to make Microsoft Learn documentation more accessible with meaningful alt text, links, tables, and visual cues.
+author: cahublou
+ms.author: cahublou
+ms.date: 08/11/2026
+ms.service: learn
+ms.topic: contributor-guide
+ms.custom: external-contributor-guide
+---
+
+# Accessibility and alt text
+
+Accessibility helps make Microsoft Learn useful for more readers, including people
+who use screen readers or other assistive technology. Small authoring choices can
+make an article easier to understand, navigate, and trust.
+
+## Write meaningful alt text
+
+Alternative text, or alt text, describes an image for readers who can't see it.
+Screen readers read alt text aloud, so the text should provide information that's
+equivalent to the visual element.
+
+Use alt text for images that convey meaning, such as screenshots, diagrams,
+charts, and flowcharts. Good alt text:
+
+- Explains the purpose or core idea of the image.
+- Is specific to the image and unique within the article.
+- Includes important product names, labels, highlighted areas, values, or states.
+- Ends with a period so screen readers pause at the end.
+- Uses about 40 to 150 characters when possible.
+
+## Avoid redundant or unhelpful alt text
+
+Don't use alt text that only repeats the file name, the surrounding sentence, or
+a generic label. Avoid phrases such as "image of" or "graphic of" because screen
+readers already announce images.
+
+Use phrases such as "Screenshot of" or "Diagram that shows" when the type of
+visual helps readers understand the content.
+
+- **Use**: "Diagram that shows a client sending requests through an API gateway."
+- **Avoid**: "Image of API gateway diagram."
+- **Avoid**: "api-gateway.png"
+- **Avoid**: "Diagram"
+
+## Add long descriptions for complex images
+
+Complex images include architecture diagrams, graphs, decision trees, and process
+flowcharts. If the visual includes more information than alt text can cover, use
+the Learn `:::image type="complex":::` syntax and add a long description.
+
+The long description should include the important relationships, values, text,
+and data that readers need to understand the visual.
+
+## Mark decorative images correctly
+
+Decorative images and icons don't convey information. Don't add alt text to
+decorative images. Instead, use the Learn image syntax with `type="icon"` so the
+published page uses an empty alt attribute.
+
+## Use descriptive link text
+
+Write link text that describes the destination or action. Descriptive link text
+helps readers understand where a link goes without relying on surrounding text.
+
+- **Use**: "Read the Markdown reference."
+- **Avoid**: "Click here."
+- **Avoid**: "Learn more."
+
+## Make tables accessible
+
+Use simple tables with clear header rows. Avoid merged cells because they can
+make relationships between headers and data difficult to follow. If a table
+becomes too complex, consider rewriting the information as headings and lists.
+
+## Don't rely on color alone
+
+Color can help draw attention, but it shouldn't be the only signal. Use text,
+labels, position, or other descriptions so readers who can't distinguish the
+color still understand the meaning.
+
+## Check build warnings
+
+The Microsoft Learn build validates alt text. Missing alt text, duplicate alt
+text, and alt text that uses a bad value such as the image file name can cause
+warnings. Resolve these warnings before submitting or updating a pull request.

Contribute/content/add-images.md

@@ -0,0 +1,94 @@
+---
+title: Add images and screenshots to documentation
+description: Learn how to add images and screenshots to Microsoft Learn documentation.
+author: cahublou
+ms.author: cahublou
+ms.date: 08/11/2026
+ms.topic: contributor-guide
+ms.service: learn
+ms.custom: external-contributor-guide
+---
+
+# Add images and screenshots to documentation
+
+Images can clarify steps and provide helpful context when they're used in moderation. Use images only when they help readers complete a task or understand an important concept.
+
+## Choose an image syntax
+
+Microsoft Learn supports standard Markdown image syntax and the Learn `:::image:::` extension. For more syntax details, see the [Images section in the Markdown reference](markdown-reference.md#images).
+
+Use standard Markdown for simple images:
+
+```md
+![<alt text>](media/<article-name>/<image-file-name>.png)
+```
+
+Use the Learn `:::image:::` extension when you need Learn-specific image features, such as automatic borders, complex image descriptions, or localization scope:
+
+```md
+:::image type="content" source="media/<article-name>/<image-file-name>.png" alt-text="<alt text>":::
+```
+
+For standard content images, `source` and `alt-text` are required. For complex images, such as charts or diagrams that need more explanation for screen reader users, include a long description:
+
+```md
+:::image type="complex" source="media/<article-name>/<image-file-name>.png" alt-text="<alt text>":::
+   <long description here>
+:::image-end:::
+```
+
+## Store image files with the article
+
+Store images in a `media` folder next to the article. Use a subfolder that matches the article file name. For example, images for `add-images.md` belong in `media/add-images/`.
+
+Reference images by using a relative path from the article:
+
+```md
+:::image type="content" source="media/add-images/example-screenshot.png" alt-text="Screenshot of an example page.":::
+```
+
+Don't store images in an `includes` folder. Images in `includes` folders might not display in published content.
+
+## Name image files clearly
+
+Use meaningful file names that describe the image. Don't use autogenerated screen capture names, such as names produced by snipping tools. Rename the file before you add it to your pull request.
+
+Use the naming pattern already used by the article or repo. Keep names specific enough that another contributor can understand what the image shows.
+
+## Use supported formats and reduce file size
+
+The default supported image formats are `.png` and `.jpg`. Other formats, such as `.gif`, must be configured as resources in the repo before they're used.
+
+Save screenshots as `.png`. Compress or resize large images before adding them. Large images can be hard to review and might not render correctly in some editing views. If an image is larger than 1 MB, check the pull request preview to make sure it renders correctly.
+
+## Always provide alt text
+
+Every documentation image must include meaningful alternate text. Alt text helps screen reader users and also appears when an image doesn't render. For more guidance, see [Accessibility](accessibility.md).
+
+Write alt text as a short sentence that starts with a capital letter and ends with a period. Describe the purpose or meaning of the image, not the file name.
+
+Instead of this:
+
+```md
+![ADextension_2FA_Configure_Step4](media/example/ADextension_2FA_Configure_Step4.PNG)
+```
+
+Write this:
+
+```md
+![Active Directory extension for two-factor authentication, step 4: Configure.](media/example/ad-extension-2fa-configure-step-4.png)
+```
+
+## Create secure screenshots
+
+Before you capture a screenshot, remove or replace sensitive information and personally identifiable information (PII). Don't rely on cropping alone if the sensitive information is still visible in the image.
+
+Scrub or replace information such as:
+
+- Real names, usernames, aliases, and email addresses.
+- Subscription names and subscription IDs.
+- Resource names, computer names, endpoints, host names, and IP addresses.
+- Passwords, keys, tokens, secrets, and connection strings.
+- Browser favorites, extension icons, or toolbars that reveal personal, internal, or sensitive information.
+
+Use unambiguously fictitious values in screenshots. If you capture Azure portal screenshots, use a customer view unless the article specifically documents a preview feature. You can also use browser developer tools, a screenshot scrubbing tool, or an image editor to replace sensitive values before you save the final single-layer image.

Contribute/content/ai-authoring-tools.md

@@ -0,0 +1,58 @@
+---
+title: AI-assisted authoring tools for Microsoft Learn
+description: Learn how AI-assisted tools in Visual Studio Code can help you author Microsoft Learn documentation.
+ms.topic: contributor-guide
+ms.service: learn
+ms.custom: external-contributor-guide
+author: cahublou
+ms.author: cahublou
+ms.date: 08/11/2026
+---
+
+# AI-assisted authoring tools for Microsoft Learn
+
+AI-assisted authoring tools can help you draft, review, and refine documentation in Visual Studio Code. These tools are optional aids. You can still contribute to Microsoft Learn by using the standard workflow and the [Learn Authoring Pack](how-to-write-docs-auth-pack.md).
+
+This article introduces two AI-assisted tools that might be useful when you work on Microsoft Learn Markdown files:
+
+- Microsoft Learn Authoring Assistant
+- GitHub Copilot for Visual Studio Code
+
+Availability and features can vary by account, repository, organization settings, and extension access. If a tool isn't available to you, continue using the Learn Authoring Pack and the guidance in this contributor guide.
+
+## Microsoft Learn Authoring Assistant
+
+Microsoft Learn Authoring Assistant is a Visual Studio Code extension that works with GitHub Copilot Chat to help improve Learn Markdown content. It reviews Markdown files and suggests edits for issues such as grammar, voice, clarity, readability, and Microsoft writing guidance.
+
+Depending on your setup, the Authoring Assistant can show suggested edits in Visual Studio Code so you can review them before making changes. You can accept a suggestion, adjust it manually, or leave your original text unchanged.
+
+The Authoring Assistant is designed to support review, not replace it. Always check suggestions for technical accuracy, context, and the needs of the article's audience.
+
+## GitHub Copilot for documentation
+
+GitHub Copilot for Visual Studio Code can help with documentation authoring by providing writing suggestions and help with code examples as you work. For example, you might use Copilot to brainstorm wording, revise a paragraph, or draft example code that you then test and verify.
+
+Copilot suggestions are AI-generated. Review them carefully before using them in Microsoft Learn content. Make sure any suggested text is accurate, original, appropriate for the article, and aligned with Microsoft Learn style and contribution requirements.
+
+## Use these tools with the Learn Authoring Pack
+
+The Learn Authoring Pack remains the core Visual Studio Code extension pack for Microsoft Learn Markdown authoring. It includes tools for Markdown support, previews, templates, linting, spelling, YAML assistance, and image handling.
+
+Use AI-assisted tools alongside the Learn Authoring Pack when they're available to you. For example, you can use the Learn Authoring Pack to preview and validate Markdown, then use an AI-assisted tool to help refine wording or review style suggestions.
+
+## Install or enable the tools
+
+To use these tools in Visual Studio Code, start with the standard setup for major documentation contributions:
+
+1. Install Visual Studio Code.
+1. Install the Learn Authoring Pack.
+1. Open the root folder of your cloned documentation repository in Visual Studio Code.
+
+To try Microsoft Learn Authoring Assistant, open the Visual Studio Code Extensions view and search for **Microsoft Learn Authoring Assistant**. If the extension is available to you, install it and follow any sign-in prompts. Some features might require specific account access or GitHub Copilot Chat.
+
+To try GitHub Copilot, make sure GitHub Copilot is enabled for your GitHub account. In Visual Studio Code, open the Extensions view, search for **GitHub Copilot**, and install the extension. If you want Copilot suggestions in Markdown files, check the GitHub Copilot extension settings and enable Markdown support if it isn't already enabled.
+
+## Next steps
+
+- [Install content-authoring tools](get-started-setup-tools.md)
+- [Learn Authoring Pack for Visual Studio Code](how-to-write-docs-auth-pack.md)

Contribute/content/contributor-license-agreement.md

@@ -0,0 +1,85 @@
+---
+title: Contributor License Agreement
+description: Learn when external contributors are asked to complete the Microsoft Contributor License Agreement for Microsoft Learn documentation pull requests.
+author: cahublou
+ms.author: cahublou
+ms.date: 08/11/2026
+ms.topic: contributor-guide
+ms.service: learn
+ms.custom: external-contributor-guide
+---
+
+# Contributor License Agreement
+
+Microsoft welcomes contributions from the community to Microsoft Learn
+documentation repositories on GitHub. If you open a pull request (PR) to a
+public Microsoft Learn repository and you aren't a Microsoft employee, you
+might be asked to complete the Microsoft Contributor License Agreement (CLA).
+
+The CLA is a short, one-time step that helps Microsoft process community
+contributions. It's part of the PR validation workflow for public repositories.
+After the CLA step is cleared, your PR continues through the rest of the
+validation and review process.
+
+## When you're asked to complete the CLA
+
+You might be asked to complete the CLA the first time you submit a substantial
+PR to a public Microsoft Learn repository. Whether the CLA check appears can
+depend on the amount of change in the PR.
+
+Microsoft employees don't need to complete this step for Microsoft Learn
+documentation contributions.
+
+If your PR requires a CLA, GitHub shows a License/CLA check on the PR. When the
+check is queued or waiting, the PR can't finish processing until the CLA step is
+complete.
+
+## How the CLA flow works
+
+The CLA flow happens in the GitHub PR conversation. You don't need to leave the
+PR or start over.
+
+1. Open your PR in GitHub.
+1. Review the checks and comments on the PR.
+1. If the License/CLA check is queued, follow the CLA-bot instructions in the
+   PR conversation.
+1. Comment on the PR with the appropriate CLA-bot command.
+1. Wait for the License/CLA check to update.
+
+After the check clears, the PR continues through the normal Microsoft Learn PR
+workflow, such as labeling, validation, build, staging, review, and possible
+merge.
+
+## Sign as an individual or a company
+
+The CLA can be completed for an individual or for a company. Choose the option
+that matches how you're contributing.
+
+To agree on behalf of yourself as an individual, comment on the PR with:
+
+```markdown
+@microsoft-github-policy-service agree
+```
+
+To agree on behalf of a company, comment on the PR with:
+
+```markdown
+@microsoft-github-policy-service agree company="your company"
+```
+
+After the CLA is completed for the same individual or company, it shouldn't need
+to be completed again for future Microsoft Learn documentation PRs from that
+same legal entity.
+
+## If your contribution status changes
+
+If you need to revoke a previous CLA agreement because your company or
+contribution status changed, comment on the PR with:
+
+```markdown
+@microsoft-github-policy-service terminate
+```
+
+If the CLA check doesn't update after you follow the PR instructions, wait a
+short time and refresh the PR. The rest of the PR checks can continue only after
+the CLA step clears.

Contribute/content/create-pull-request.md

@@ -6,7 +6,7 @@ ms.author: cahublou
 ms.topic: contributor-guide
 ms.service: learn
 ms.custom: external-contributor-guide
-ms.date: 01/25/2024
+ms.date: 08/11/2026
 ---
 
 # Create a pull request in GitHub
@@ -45,12 +45,12 @@ After you've updated or added your content, it's time to create a pull request (
 1. On the **Open a pull request** page, verify that:
 
    - The **base repository:** matches the upstream repository (for example, *MicrosoftDocs/azure-docs*).
-   - The **base:** branch is set to the default branch (most likely named *main*) in the upstream repository. All your changes will be merged to the upstream branch.
+   - The **base:** branch is set to the branch you want to merge into in the upstream repository. Most of the time this is the default branch (usually named *main*). If you're contributing to a repository that uses a *release branch* for your change, set **base:** to that release branch instead. All your changes will be merged to the branch you select here.
    - The number of commits and files changed is what you expect.
 
 :::image type="content" source="media/create-pull-request/comparing-changes.png" alt-text="Screenshot of the Comparing changes screen in GitHub.":::
 
-1. Your first commit message on your branch becomes the default PR title. If you want, edit the title to make it more appropriate for a PR (for example: Update prerequisites list).
+1. The commit message from your branch is used as the default PR title. If you want, edit the title to make it more appropriate for a PR (for example: Update prerequisites list). Clear or update the description box as needed.
 
 1. Add an optional description. A description helps reviewers understand the purpose of your PR. For example, you can describe the problem you're trying to solve or the reason you're making the change.