diff --git a/Contribute/content/TOC.yml b/Contribute/content/TOC.yml index 0da618e5..96d2b11d 100644 --- a/Contribute/content/TOC.yml +++ b/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 diff --git a/Contribute/content/accessibility.md b/Contribute/content/accessibility.md new file mode 100644 index 00000000..1b79419b --- /dev/null +++ b/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. diff --git a/Contribute/content/add-images.md b/Contribute/content/add-images.md new file mode 100644 index 00000000..60eb3abe --- /dev/null +++ b/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 +![](media//.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//.png" 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//.png" alt-text=""::: + +:::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. diff --git a/Contribute/content/ai-authoring-tools.md b/Contribute/content/ai-authoring-tools.md new file mode 100644 index 00000000..1ca89fda --- /dev/null +++ b/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) diff --git a/Contribute/content/contributor-license-agreement.md b/Contribute/content/contributor-license-agreement.md new file mode 100644 index 00000000..02fbf316 --- /dev/null +++ b/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. diff --git a/Contribute/content/create-pull-request.md b/Contribute/content/create-pull-request.md index 3025eee7..d3fe5b39 100644 --- a/Contribute/content/create-pull-request.md +++ b/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. diff --git a/Contribute/content/get-started-setup-tools.md b/Contribute/content/get-started-setup-tools.md index 84db8121..09aae640 100644 --- a/Contribute/content/get-started-setup-tools.md +++ b/Contribute/content/get-started-setup-tools.md @@ -7,7 +7,7 @@ ms.service: learn ms.custom: external-contributor-guide author: carlyrevier ms.author: cahublou -ms.date: 09/27/2023 +ms.date: 08/11/2026 --- # Install content-authoring tools @@ -84,6 +84,10 @@ To use the Learn Authoring Pack functionality, press `Alt+M` in Visual Studio Co For more information, see [Learn Authoring Pack for Visual Studio Code](how-to-write-docs-auth-pack.md). +## Optional: AI-assisted authoring tools + +Beyond the Learn Authoring Pack, optional AI-assisted tools such as the Learn Authoring Assistant and GitHub Copilot can help you draft and refine content in Visual Studio Code. Availability of some features depends on your setup and access. For more information, see [AI-assisted authoring tools](ai-authoring-tools.md). + ## Understand Markdown editors Markdown is a lightweight markup language used to author the content. [Visual Studio Code](https://code.visualstudio.com/) is the preferred tool for editing Markdown at Microsoft. Other Markdown editing tools are available. The [Markdown Reference](markdown-reference.md) article covers Markdown basics and the features supported by the `learn.microsoft.com` website. diff --git a/Contribute/content/how-to-create-github-issues.md b/Contribute/content/how-to-create-github-issues.md index f4c85632..1cbdb0f2 100644 --- a/Contribute/content/how-to-create-github-issues.md +++ b/Contribute/content/how-to-create-github-issues.md @@ -3,7 +3,7 @@ title: Create GitHub issues for open-source products description: Learn how to create issues in GitHub to alert the content team when you spot errors in Microsoft Learn documentation for open-source products. author: carlyrevier ms.author: cahublou -ms.date: 02/23/2024 +ms.date: 08/11/2026 ms.topic: contributor-guide ms.service: learn ms.custom: external-contributor-guide @@ -27,11 +27,11 @@ Of course, if you know how to fix an issue, we invite you to [make the changes y ## Create an issue 1. Navigate to the article you want to comment on. -1. Scroll to the bottom of the article, where you'll see options for submitting feedback. Select **Open a documentation issue** to create a new issue. This feedback is specific to the content and is tracked as an issue in GitHub. +1. Scroll to the bottom of the article, where you'll see options for submitting feedback. Select **This page** to open the feedback experience and create a new issue. This feedback is specific to the content and is tracked as an issue in GitHub. ![Screenshot of the bottom of an article, showing the feedback options.](media/how-to-create-github-issues/feedback-links.png) - Optionally, select **Provide product feedback** to go to a destination (for example, a feedback portal, GitHub, an email address) where you can provide feedback on the product itself. This feedback is independent of the content and has no relationship back to the original article. + Optionally, select **This product** to go to a destination (for example, a feedback portal, GitHub, an email address) where you can provide feedback on the product itself. This feedback is independent of the content and has no relationship back to the original article. 1. The system opens a new issue for you in the GitHub repository that stores the content for the article you're viewing. Add a title and a description; all other fields should populate for you automatically. When you're done, select **Submit new issue**. diff --git a/Contribute/content/how-to-write-docs-auth-pack.md b/Contribute/content/how-to-write-docs-auth-pack.md index f0a8ca35..d045f25c 100644 --- a/Contribute/content/how-to-write-docs-auth-pack.md +++ b/Contribute/content/how-to-write-docs-auth-pack.md @@ -6,7 +6,7 @@ ms.service: learn ms.custom: external-contributor-guide author: meganbradley ms.author: mbradley -ms.date: 01/09/2023 +ms.date: 08/11/2026 --- # Learn Authoring Pack for Visual Studio Code @@ -20,6 +20,8 @@ The Learn Authoring Pack is a collection of Visual Studio Code extensions to aid > - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker): A fully offline spell checker by Street Side Software. > - [Learn Preview](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-preview): Uses the Microsoft Learn CSS for more accurate Markdown preview, including custom Markdown. > - [Learn Article Templates](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-article-templates): Allows users to scaffold Learn modules and apply Markdown skeleton content to new files. +> - Learn Scaffolding: Automatically generates Learn training modules based on standard patterns and automates renaming, inserting, deleting, and reordering units. +> - Cleanup scripts: Perform bulk operations to clean up common issues in the repository. > - [Learn YAML](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-yaml): Provides YAML schema validation and auto-complete. > - [Learn Images](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-images): Provides image compression and resizing for folders and individual files to help authors of Microsoft Learn content. diff --git a/Contribute/content/how-to-write-major-edits.md b/Contribute/content/how-to-write-major-edits.md index 6fa07358..5f18e701 100644 --- a/Contribute/content/how-to-write-major-edits.md +++ b/Contribute/content/how-to-write-major-edits.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 --- # Make major changes to Microsoft Learn documentation @@ -45,6 +45,9 @@ This tutorial uses Git Bash and Visual Studio Code, but you can use any Git clie 1. In the integrated terminal, make sure you're in the repository folder. 1. Before you create a working branch, make sure your local main branch is current with everything in the production repo's main branch. This task ensures your working branch captures any changes that have happened in the production repo since the last time you synced with it. + > [!NOTE] + > Most of the time, `main` (the default branch) is the right branch to base your work on. Some repositories use a *release branch* for certain changes instead. If the repository you're contributing to uses release branches, substitute the appropriate branch name for `main` in the following steps and when you open your pull request. + 1. Switch to the main branch in your local repository: ```Console diff --git a/Contribute/content/metadata.md b/Contribute/content/metadata.md index 09440ec4..9697c563 100644 --- a/Contribute/content/metadata.md +++ b/Contribute/content/metadata.md @@ -3,7 +3,7 @@ title: Metadata for Microsoft Learn documentation description: Learn about the required and optional metadata for Microsoft Learn documentation. author: sarah-barrett ms.author: sabarret -ms.date: 05/01/2025 +ms.date: 08/11/2026 ms.topic: contributor-guide ms.service: learn ms.custom: external-contributor-guide @@ -37,6 +37,8 @@ The following table shows the required metadata attributes. If you omit any of t | description | A summary of the content. 75-300 characters. | Used in site search. Sometimes used on a search engine results page for improved SEO. | | ms.author |The author's Microsoft alias, *without* "@microsoft.com". If you aren't a Microsoft employee, find a suitable Microsoft employee to use in this field. | Identifies the article's owner. The owner is responsible for decisions about the content of the article, and for the article's reporting and BI. | | ms.date | A date in the format MM/DD/YYYY. | Displayed on the published page to indicate the last time the article was substantially edited or guaranteed fresh. The date is entered without time and is interpreted as 0:00 and in the UTC time zone. The date displayed to users is converted to their time zone. | +| ms.topic | The type of article, chosen from an allowlist (for example, conceptual, how-to, overview, quickstart). | Identifies the content type for reporting and platform behavior. | +| ms.service | The product or service the article is about, chosen from an allowlist. Add ms.subservice as well when it's relevant for the service you set. | Used to report on content by product. (The platform has retired ms.prod and ms.technology in favor of ms.service and ms.subservice.) | | title | The page title. | This is the page title that's displayed on the browser tab. It's the most important metadata for SEO. | Attributes are case-sensitive. Enter them exactly as listed, and use a colon and a space between the attributes and the value. If an attribute value includes a colon (:), a hash (#), or any other special character, you must enclose it either single (') or double (") quotes. For example: diff --git a/Contribute/content/process-pull-request.md b/Contribute/content/process-pull-request.md index ff9d6bee..9924b438 100644 --- a/Contribute/content/process-pull-request.md +++ b/Contribute/content/process-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 --- # Process a pull request @@ -42,7 +42,7 @@ Each time you add a commit to the same working branch, the commit is added autom ## Sign-off and comment automation -When you've addressed all feedback and validation errors, and you're ready for your changes to be merged, it's time to sign off on your PR by creating a new comment that reads `#sign-off`. You must enter the `#sign-off` comment to merge your changes. Even if all reviews and validation checks pass, you're responsible for using this comment to tell the PR reviewers and repo admins that your changes are ready for merging. +When you've addressed all feedback and validation errors, and you're ready for your changes to be merged, it's time to signal that the PR is ready. The exact merge method is repository-specific: in many repositories (for example, the Azure docs repository) you sign off by creating a new comment that reads `#sign-off`. In some other repositories (for example, the .NET and ASP.NET docs repositories) you select the **Squash and merge** button instead. Check the repository's contributing guidance if you're unsure. Even if all reviews and validation checks pass, you're responsible for signaling that your changes are ready so PR reviewers and repo admins know to merge them. When the reviewers determine that your PR is issue-free and signed off, your changes are merged into the default branch and the PR is closed. diff --git a/Contribute/content/provide-feedback.md b/Contribute/content/provide-feedback.md index d0636291..e3eb3ff7 100644 --- a/Contribute/content/provide-feedback.md +++ b/Contribute/content/provide-feedback.md @@ -6,7 +6,7 @@ ms.author: cahublou ms.topic: contributor-guide ms.service: learn ms.custom: external-contributor-guide -ms.date: 02/22/2024 +ms.date: 08/11/2026 --- # Provide feedback for Microsoft Learn content @@ -56,7 +56,7 @@ To leave feedback using the standard experience: Some content teams may also configure these other links to appear at the bottom of the feedback control: - - **Provide product feedback**: This link allows you to provide feedback for the product itself rather than the content. Selecting this link will take you to a platform where you can provide feedback on the product, which is reviewed by the respective product teams. + - **This product**: This link allows you to provide feedback for the product itself rather than the content. Selecting this link will take you to a platform where you can provide feedback on the product, which is reviewed by the respective product teams. - **Get help**: Depending on how this link is configured, it takes you to either the product's community site or the Q&A platform. If you have specific questions and require community assistance, you can use these platforms to get help. 1. Select **Submit**.