diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7b29b75140..0e052d01ea 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,48 +2,34 @@ ## Disclosure -IMPORTANT: For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. Add the following frontmatter key/value pair: +IMPORTANT: For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. If missing, add the `ai-usage` frontmatter key/value pair: -```markdown -ai-usage: ai-generated -``` - -## Terminology +- When reviewing a PR not created by AI: -- Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework). + ```markdown + ai-usage: ai-assisted + ``` -## Writing Style +- When Copilot generates the article through GitHub without the use of a human: -Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics: + ```markdown + ai-usage: ai-generated + ``` -### Voice and Tone +- When using an IDE with a human guiding AI: -- Active voice, second person addressing reader directly. -- Conversational tone with contractions. -- Present tense for instructions/descriptions. -- Imperative mood for instructions ("Call the method" not "You should call the method"). -- Use "might" instead of "may" for possibility. -- Use "can" instead of "may" for permissible actions. -- Avoid "we"/"our" referring to documentation authors or product teams. + ```markdown + ai-usage: ai-assisted + ``` -### Structure and Format +## New articles -- Sentence case headings (no gerunds in titles). -- Be concise, break up long sentences. -- IMPORTANT: Oxford comma in lists. -- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.) -- IMPORTANT: Use bullets for unordered lists. -- VERY IMPORTANT: Ordered and unordered lists should use complete sentences with proper punctuation, ending with a period if it's more than three words. -- Avoid "etc." or "and so on" - provide complete lists or use "for example". -- No consecutive headings without content between them. +- New articles must follow a template in the /.github/projects/article-templates/ folder. +- If you don't know which template to use, ask. -### Formatting Conventions +## Terminology -- **Bold** for UI elements. -- `Code style` for file names, folders, custom types, non-localizable text. -- Raw URLs in angle brackets. -- Use relative links for files in this repo. -- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links. +- Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework). ## API References @@ -66,11 +52,66 @@ For snippets >6 lines: 1. Create examples in both C# and Visual Basic unless the article referencing the snippet resides in the in the `csharp`, `fsharp`, and `visual-basic` language folders. 1. When you add code, use code comments sparingly because they don't get localized. You can use them to briefly clarify code-specific details (such as logic, parameters, or edge cases). Put any critical information and context in the markdown text of the referencing article. +## .NET Framework vs .NET differences + +When documenting differences between .NET Framework and .NET (like .NET 6 and newer), choose the appropriate system: + +### Use Tabs +Use tabbed content when the differences are code-based: + +```markdown +# [.NET](#tab/dotnet) + + + +# [.NET Framework](#tab/dotnetframework) + + + +--- +``` + +### Use Pivots +Use zone pivots when there are conceptual differences that can't easily be explained with tabs and a note. Pivots allow for more comprehensive explanations of different approaches or methodologies. + +To use zone pivots: + +1. Add `zone_pivot_groups: dotnet-version` to the article's frontmatter +2. Use zone pivot syntax in content: + +```markdown +::: zone pivot="dotnet" + +Your .NET content here + +::: zone-end + +::: zone pivot="dotnetframework" + +Your .NET Framework content here + +::: zone-end +``` + ## File Naming New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.). +Examples: +- ✅ Good: `getting-started-with-entity-framework.md` +- ✅ Good: `configure-logging.md` +- ✅ Good: `dependency-injection-guidelines.md` +- ❌ Bad: `Getting-Started-With-The-Entity-Framework.md` +- ❌ Bad: `configure_logging.md` +- ❌ Bad: `DependencyInjectionGuidelines.md` + ## Special Cases -- Breaking changes: Include directions from `.github/prompts/breaking-change.md`. -- When you (Copilot) are assigned an issue in GitHub, after you've completed your work and the workflows (status checks) have run, check to make sure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced. +### GitHub Issue Assignment (AI Workflow) +When assigned an issue in GitHub: +1. Complete your work +2. Wait for workflows (status checks) to run +3. Check for build warnings in the OpenPublishing.Build status check +4. If warnings exist: + - Click "View Details" to open the build report + - Resolve any build warnings you introduced diff --git a/.github/instructions/Markdown.WritingStyle.instructions.md b/.github/instructions/Markdown.WritingStyle.instructions.md new file mode 100644 index 0000000000..eb72f1e320 --- /dev/null +++ b/.github/instructions/Markdown.WritingStyle.instructions.md @@ -0,0 +1,83 @@ +--- +applyTo: 'dotnet-desktop-guide/**/*.md' +description: 'Follow these comprehensive writing style guidelines when creating or editing Markdown documentation. Apply active voice, conversational tone, Oxford commas, and specific formatting rules to ensure consistency and readability across all documentation.' +--- + +# Markdown Writing Style Instructions + +When writing or editing Markdown documentation, follow these style guidelines: + +## Voice and Tone Requirements + +ALWAYS write using: +- Active voice with second person ("you") +- Conversational tone with contractions +- Present tense for instructions and descriptions +- Imperative mood for instructions (write "Call the method" NOT "You should call the method") +- "might" for possibility (NOT "may") +- "can" for permissible actions (NOT "may") + +NEVER use: +- "we" or "our" when referring to documentation authors or product teams +- Jargon or overly complex technical language +- Weak phrases like "you can" or "there is/are/were" unless they add value + +ALWAYS: +- Write like you speak using everyday words +- Create a friendly, informal tone +- Start statements with verbs when possible + +## Structure and Format Rules + +### Headings and Content +- Use sentence case headings (capitalize only first word and proper nouns) +- Never use gerunds in titles +- Never place consecutive headings without content between them +- Lead with the most important information first +- Front-load keywords for scanning + +### Lists and Punctuation +- **CRITICAL: Use Oxford comma in ALL lists (item1, item2, and item3) - NO EXCEPTIONS** +- **MANDATORY: Number ordered lists using "1." for every item (NOT 1., 2., 3.) - ALWAYS USE "1."** +- **REQUIRED: Use bullets for unordered lists - NEVER use numbers for unordered content** +- **ESSENTIAL: Write complete sentences in lists with proper punctuation** +- **MUST: End list items with periods if more than three words - THIS IS NON-NEGOTIABLE** +- Skip end punctuation on titles, headings, and UI elements (3 words or fewer) + +### Spacing and Layout +- Add blank lines around Markdown elements (but don't add extra if they exist) +- Use only one space after periods, question marks, and colons +- Use no spaces around dashes (word—word) +- Break up long sentences for clarity + +### Prohibited Terms +- Never write "etc." or "and so on" - provide complete lists or use "for example" +- Use "for example" instead of "e.g." +- Use "that is" instead of "i.e." + +## Formatting Conventions + +Apply these formatting rules: +- **Bold text** for UI elements +- `Code style` for file names, folders, custom types, and non-localizable text +- Raw URLs in angle brackets +- Relative links for files in this repository +- Remove `https://learn.microsoft.com/en-us` from Microsoft Learn links + +## Word Choice Requirements + +### Verb Selection +- Choose simple verbs without modifiers +- Avoid weak verbs: "be," "have," "make," "do" +- Use precise verbs (write "tell" NOT "inform") + +### Conciseness Rules +- Use one word instead of multiple when possible (write "to" NOT "in order to") +- Choose words with one clear meaning (write "because" NOT "since" for causation) +- Omit unnecessary adverbs unless critical to meaning +- Use one term consistently for each concept + +### Contraction Guidelines +- Use common contractions: "it's," "you're," "that's," "don't" +- Avoid ambiguous contractions: "there'd," "it'll," "they'd" +- Never form contractions from noun + verb (avoid "Microsoft's developing") \ No newline at end of file diff --git a/.github/instructions/Snippets.Migrate.instructions.md b/.github/instructions/Snippets.Migrate.instructions.md new file mode 100644 index 0000000000..f863d39e57 --- /dev/null +++ b/.github/instructions/Snippets.Migrate.instructions.md @@ -0,0 +1,142 @@ +--- +description: Migrate code from the old ~/samples/snippets/ location to the relative ./snippets location. +--- + +# Migrate code snippets + +**IMPORTANT**: Unless otherwise asked to, **only** edit the article file in context. At the end of your operations you may ask for permission to edit other articles referencing the same snippets. + +## Repository structure for code snippets + +**IMPORTANT**: This repository has TWO different locations for code snippets: + +### Old location (legacy - to be migrated FROM) +- Path: `~/samples/snippets/` +- Example: `~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.Clipboard/CS/form1.cs` +- Status: Legacy, should be migrated to new location + +### New location (current standard - migrate TO) +- Path pattern: `./snippets/{doc-file}/[net-or-framework]/{code-language}/` +- Example: `./snippets/how-to-add-data-to-the-clipboard/net/csharp/form1.cs` + +**Path components explained:** +- `{doc-file}`: The markdown article filename WITHOUT the `.md` extension + - Example: For article `how-to-add-data-to-the-clipboard.md` → use `how-to-add-data-to-the-clipboard` +- `[net-or-framework]`: Choose based on target framework: + - `net`: For .NET (.NET 6 and newer) + - `framework`: For .NET Framework (4.8 and older) + - **Rule**: Only include this subfolder when the article demonstrates BOTH .NET and .NET Framework approaches +- `{code-language}`: + - `csharp`: For C# code + - `vb`: For Visual Basic code + +## Legacy code characteristics (migrate FROM these) + +**Location**: `~/samples/snippets/` folder +**Problems with legacy code:** +- Written for .NET Framework (outdated) +- Often incomplete or non-compilable +- May lack project files +- Uses outdated syntax and patterns + +**Legacy article references look like this:** +```markdown +[!code-{code-language}[description](~/samples/snippets/{path-to-file}#{snippet-identifier})] +``` + +## Current code requirements (migrate TO these) + +**Location**: `./snippets/{doc-file}/[framework]/{code-language}/` + +**Requirements for current code standards:** +- ✅ MUST be complete and compilable +- ✅ MUST include a project file +- ✅ MUST target appropriate .NET version (see targeting rules below) +- ✅ MUST provide BOTH C# and Visual Basic versions +- ✅ MUST use appropriate syntax for the target framework +- ✅ MUST use meaningful, descriptive snippet identifiers in CamelCase format + - **Examples** of good snippet identifiers: `BasicClipboardData`, `CustomDataFormat`, `ClipboardImageHandling` + - **Avoid** simplistic identifiers like `1`, `2`, `code1`, or `snippet1` + +**Current article references look like this:** +```markdown +:::code language="{code-language}" source="{file-path}" id="{snippet-identifier}"::: +``` + +**Framework targeting rules:** +- **Migration vs. Modernization**: + - **Migration**: Move code to new location with minimal changes + - **Modernization**: Update code to use latest .NET features and best practices +- **When to migrate only**: When article has `ms.service: dotnet-framework` frontmatter or is specifically about .NET Framework features +- **When to modernize**: When article demonstrates both .NET and .NET Framework, or when specifically requested +- **Default targeting**: + - For .NET Framework-specific articles: Keep targeting .NET Framework + - For general articles: Target latest .NET version (e.g., .NET 10) + - For mixed articles: Create separate snippets in `net/` and `framework/` subfolders + +## Migration steps (follow in order) + +**WHEN TO MIGRATE**: Migrate code when you encounter articles with references to `~/samples/snippets/` paths. + +**STEP-BY-STEP PROCESS:** + +### 1. Analyze existing code and article context +- **Find**: Locate the legacy snippet file in `~/samples/snippets/` +- **Check frontmatter**: Look for `ms.service: dotnet-framework` in the article's frontmatter +- **Determine scope**: + - If frontmatter has `ms.service: dotnet-framework` → this is likely a .NET Framework-specific article + - if frontmatter has `ms.service: dotnet-desktop` or similar → this is likely a dual-framework or general article + - If article demonstrates both .NET and .NET Framework → prepare for dual targeting + - If article is general purpose → consider targeting current .NET +- **Identify**: Determine the programming language (C# or Visual Basic) +- **Extract**: Note the snippet identifier used in the article reference + +### 2. Create new folder structure +- **Pattern**: `./snippets/{doc-file}/[net-or-framework]/{code-language}/` +- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/net/csharp/` +- **Decision tree for framework folder**: + - Article has `ms.service: dotnet-framework` frontmatter → use `./snippets/{doc-file}/framework/{code-language}/` + - Article shows ONLY current .NET examples → use `./snippets/{doc-file}/{code-language}/` (omit framework folder) + - Article shows BOTH .NET and .NET Framework → create both `./snippets/{doc-file}/net/{code-language}/` and `./snippets/{doc-file}/framework/{code-language}/` + +### 3. Migrate and update code +- **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location +- **Update approach**: + - **For .NET Framework articles**: Migrate with minimal changes, keep .NET Framework targeting + - **For dual-framework articles**: Create both versions with appropriate targeting and update frontmatter to `ms.service: dotnet-desktop` + - **For general articles**: Update to target current .NET only if specifically requested or if article demonstrates modernization +- **Complete**: Ensure code is fully functional and compilable +- **Project file**: Create or update project file with appropriate target framework + +### 4. Create both language versions +- **Requirement**: MUST provide both C# and Visual Basic versions +- **C# path**: `./snippets/{doc-file}/[framework]/csharp/` +- **VB path**: `./snippets/{doc-file}/[framework]/vb/` + +### 5. Update article references +- **Replace**: Change from legacy `[!code-...]` format to modern `:::code...:::` format +- **Before**: `[!code-csharp[description](~/samples/snippets/path/file.cs#snippet1)]` +- **After**: `:::code language="csharp" source="./snippets/doc-name/net/csharp/file.cs" id="BasicClipboardData":::` +- **Note**: Use meaningful CamelCase identifiers instead of simple numbers + +### 6. Validate +- **Build**: Ensure all code compiles successfully +- **Test**: Verify snippet references work in the article +- **Clean**: Remove unused legacy files (if no other articles reference them) + +### 7. Delete +- **Identify**: + - Check if the old snippet file is used by any other articles + - Some articles may use a relative path to the `samples` folder, so simply search for links to `samples/snippets/...` + - Be confident that all legacy snippets use a `samples/snippets` folder structure +- **Delete**: If old snippet is no longer used by any article, delete it. + +## Common mistakes to avoid + +- ❌ **Don't** assume all code needs to be modernized - check article context first +- ❌ **Don't** modernize .NET Framework-specific articles unless specifically requested +- ❌ **Don't** ignore the `ms.service: dotnet-framework` frontmatter indicator +- ❌ **Don't** forget to create both C# and VB versions +- ❌ **Don't** mix up the framework targeting (net vs framework) +- ❌ **Don't** forget to update ALL article references to the migrated code +- ❌ **Don't** leave incomplete or non-compilable code diff --git a/.github/instructions/Snippets.Push.instructions.md b/.github/instructions/Snippets.Push.instructions.md new file mode 100644 index 0000000000..aff9789dd6 --- /dev/null +++ b/.github/instructions/Snippets.Push.instructions.md @@ -0,0 +1,122 @@ +--- +description: Push inline code block snippets out of articles into standalone files with proper project structure. +--- + +# Push inline code snippets to files + +**IMPORTANT**: Unless otherwise asked to, **only** edit the article file in context. At the end of your operations you may ask for permission to edit other articles that might benefit from the same snippet extraction. + +**IMPORTANT**: Don't share code across multiple articles. Each article should have its own copy of the snippet in its own folder structure. + +## Quick Reference + +**WHEN TO PUSH:** Code >6 lines, complete/compilable examples, or when specifically requested +**FOLDER PATTERN:** `./snippets/{doc-file}/[net-or-framework]/{csharp|vb}/` +**PROJECT CREATION:** Always use `dotnet new {winforms|wpf|console|classlib}` commands to create a new project for the code language +**LANGUAGES:** Create both C# and VB versions +**SNIPPET IDs:** Use CamelCase region markers like `` +**ARTICLE REFS:** Replace with `:::code language="csharp" source="./path" id="SnippetId":::` + +## When to push snippets out of articles + +**PUSH SNIPPETS WHEN:** +- Code blocks are longer than 6 lines or the rest of the article is using them +- Code demonstrates complete, compilable examples +- Code represents a complete application or significant functionality +- User specifically requests snippet extraction + +**KEEP INLINE WHEN:** +- Code blocks are 6 lines or shorter +- Code shows configuration snippets (XAML, JSON, XML) +- Code demonstrates simple one-liner examples +- Code is pseudo-code or conceptual examples + +## Target folder structure + +**IMPORTANT**: Follow a folder structure based on the article and code language: + +### New snippet location (standard) +- Path pattern: `./snippets/{doc-file}/[net-or-framework]/{code-language}/` +- Example: `./snippets/create-windows-forms-app/net/csharp/` + +**Path components explained:** +- `{doc-file}`: The markdown article filename WITHOUT the `.md` extension + - Example: For article `create-windows-forms-app.md` → use `create-windows-forms-app` +- `[net-or-framework]`: Choose based on target framework: + - `net`: For .NET (.NET 6 and newer) + - `framework`: For .NET Framework (4.8 and older) + - **Rule**: Only include this subfolder when the article demonstrates BOTH .NET and .NET Framework approaches +- `{code-language}`: + - `csharp`: For C# code + - `vb`: For Visual Basic code + +## Framework targeting and project types + +**Determine target framework:** +- Check article frontmatter `ms.service` value: + - `dotnet-framework` → .NET Framework 4.8 + - `dotnet-desktop` → Current .NET (e.g., .NET 10) +- Examine code patterns and article content + +**Create appropriate project with `dotnet new`:** + +| Project Type | Indicators | .NET Command | .NET Framework Command | +|--------------|------------|--------------|------------------------| +| **Windows Forms** | `System.Windows.Forms`, `Form`, `/winforms/` path | `dotnet new winforms` | `dotnet new winforms --framework net48` | +| **WPF** | `System.Windows`, `Window`, XAML, `/wpf/` path | `dotnet new wpf` | `dotnet new wpf --framework net48` | +| **Console** | `Console.WriteLine`, simple examples, no UI | `dotnet new console` | `dotnet new console --framework net48` | +| **Class Library** | Reusable components, no entry point | `dotnet new classlib` | `dotnet new classlib --framework net48` | + +## Push process + +### 1. Analyze and prepare +- Locate code blocks >6 lines or complete examples +- Determine project type from code patterns and article location +- Check framework targeting from frontmatter +- Create folder structure: `./snippets/{doc-file}/[net-or-framework]/{csharp|vb}/` + +### 2. Create projects and extract code +- Run appropriate `dotnet new` command in each language folder, **don't** specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible +- Copy and complete code to make it compilable +- Add missing using statements, namespaces, class declarations +- Modernize code patterns if targeting current .NET +- Test compilation with `dotnet build` + +### 3. Add snippet references and update article +- Add CamelCase region markers: `// ` and `// ` +- Use same identifiers across C# and VB versions +- Replace inline code with snippet references: + ```markdown + :::code language="csharp" source="./snippets/doc-name/net/csharp/File.cs" id="ButtonClick"::: + :::code language="vb" source="./snippets/doc-name/net/vb/File.vb" id="ButtonClick"::: + ``` +- DO NOT use language tabs, simply put them side-by-side +- Verify all paths and references are correct + +### 4. Make sure frontmatter specifies a language when required + +If both CSharp and VB examples are provided make sure the following frontmatter is at the top of the article: + +```yml +dev_langs: + - "csharp" + - "vb" +``` + +## Common mistakes to avoid + +- ❌ Extracting short snippets (≤6 lines) without request +- ❌ Skipping `dotnet new` commands or creating incomplete projects +- ❌ Missing C# or VB versions +- ❌ Using language tabs +- ❌ Wrong project type (winforms vs wpf vs console) +- ❌ Incorrect framework targeting (net vs framework) +- ❌ Missing or inconsistent snippet region identifiers +- ❌ Code that doesn't compile + +## Quality checklist + +- ✅ Correct folder structure and project type +- ✅ Both C# and VB versions compile successfully +- ✅ Snippet regions use CamelCase identifiers +- ✅ Article uses correct `:::code...:::` syntax with valid paths \ No newline at end of file diff --git a/.github/instructions/Snippets.Upgrade.instructions.md b/.github/instructions/Snippets.Upgrade.instructions.md new file mode 100644 index 0000000000..caf0f3228d --- /dev/null +++ b/.github/instructions/Snippets.Upgrade.instructions.md @@ -0,0 +1,109 @@ +--- +description: Upgrade snippets to the latest .NET and possibly migrate from .NET Framework +--- + +# Code Snippet Upgrade Instructions + +## When to Apply These Instructions + +Apply these instructions when working with code snippets that need modernization, especially when: +- Migrating snippets from old locations +- Upgrading .NET Framework code to modern .NET +- Improving snippet quality and completeness +- Adding missing language versions (C# or VB) + +## Snippet Structure Requirements + +All snippets must follow this folder structure relative to the referencing article: + +``` +./snippets/{article-name}/[net|framework]/{language}/ +``` + +**Examples:** +- `./snippets/how-to-add-data-to-the-clipboard/net/csharp/MainForm.cs` +- `./snippets/how-to-add-data-to-the-clipboard/framework/vb/MainForm.vb` + +## Required Upgrade Actions + +### 1. File Naming and Organization +- **USE** PascalCase for class names and file names (e.g., `MainForm.cs`, `DataProcessor.cs`) +- **ORGANIZE** files logically within the language folder + +### 2. Snippet Identifiers and Naming +- **USE** meaningful, descriptive snippet identifiers in CamelCase format +- **REPLACE** simplistic identifiers (like single numbers) with descriptive snippet names +- **EXAMPLES** of good snippet identifiers: + - `BasicClipboardData` instead of `1` + - `CustomDataFormat` instead of `2` + - `ClipboardImageHandling` instead of `code1` +- **ENSURE** snippet identifiers clearly describe the code's purpose or functionality + +### 3. .NET Version and Syntax Modernization +- **TARGET** the latest stable .NET version for `/net/` folders +- **USE** modern C# features for .NET snippets: + - File-scoped namespaces + - Top-level statements where appropriate + - Pattern matching + - String interpolation + - var keyword where type is obvious + - Modern using statements + +### 4. Project File Requirements +- **USE** `dotnet new` to create the projects. Fallback to manual project creation if `dotnet new` is failing. +- **CREATE** a complete, compilable project structure +- **INCLUDE** appropriate `.csproj` or `.vbproj` file +- **TARGET** latest .NET version: `net8.0-windows` +- **ADD** necessary package references and properties + +### 5. Code Quality Standards +- **ENSURE** code compiles without warnings +- **FOLLOW** .NET naming conventions +- **USE** appropriate access modifiers +- **INCLUDE** necessary using/import statements +- **ADD** minimal but helpful code comments for complex logic + +### 6. Language Parity +- **CREATE** both C# and VB.NET versions unless the parent article is in a language-specific folder +- **MAINTAIN** functional equivalence between language versions +- **ADAPT** language-specific idioms appropriately + +## Framework-Specific Considerations + +### For .NET Framework Snippets (`/framework/` folders) +- **MAINTAIN** .NET Framework compatibility +- **AVOID** modern C# features not available in the target framework version +- **USE** classic C# syntax and patterns +- **TARGET** appropriate framework version (typically .NET Framework 4.8) + +### For Modern .NET Snippets (`/net/` folders) +- **USE** latest .NET features and syntax +- **TARGET** latest stable .NET version +- **LEVERAGE** modern performance patterns +- **UTILIZE** new APIs where beneficial + +## Example Transformation + +**Before (simple identifier):** +``` +./snippets/clipboard-article/code.cs +``` + +**After (descriptive structure):** +``` +./snippets/how-to-add-data-to-the-clipboard/net/csharp/ +├── ClipboardExample.csproj +├── MainForm.cs +└── Program.cs +``` + +## Validation Checklist + +Before completing snippet upgrades, verify: +- [ ] Files have descriptive, meaningful names +- [ ] Project compiles without errors or warnings +- [ ] Code follows .NET naming conventions +- [ ] Appropriate target framework is specified +- [ ] Both C# and VB versions exist (when required) +- [ ] Modern syntax is used for .NET snippets +- [ ] Framework-compatible syntax for .NET Framework snippets \ No newline at end of file diff --git a/.github/projects/article-templates/doc-guide.yml b/.github/projects/article-templates/doc-guide.yml new file mode 100644 index 0000000000..b50351bfc0 --- /dev/null +++ b/.github/projects/article-templates/doc-guide.yml @@ -0,0 +1,14 @@ +# ms.topic: version 1.0.0 +items: +- name: + href: + required: yes + limit: 1 +- name: + href: + required: yes + limit: 1 +- name: + href: + required: No + limit: none \ No newline at end of file diff --git a/.github/projects/article-templates/doc-toc.yml b/.github/projects/article-templates/doc-toc.yml new file mode 100644 index 0000000000..6b3f387f43 --- /dev/null +++ b/.github/projects/article-templates/doc-toc.yml @@ -0,0 +1,14 @@ +# ms.topic: version 1.0.0 +items: +- name: + href: //toc.yml + required: yes + limit: 1 +- name: + href: //toc.yml + required: yes + limit: 1 +- name: + href: //toc.yml + required: yes + limit: none \ No newline at end of file diff --git a/.github/projects/article-templates/general-troubleshoot.md b/.github/projects/article-templates/general-troubleshoot.md new file mode 100644 index 0000000000..df11fb27d6 --- /dev/null +++ b/.github/projects/article-templates/general-troubleshoot.md @@ -0,0 +1,143 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: troubleshooting-general #Don't change. +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Troubleshoot [issues with a product or service] + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## [Potential quick workarounds] + +1. Procedure step +1. Procedure step + + + +## [Troubleshooting checklist] + +### [Troubleshooting step] + + + +## [Causes and/or solutions] + +### [Solution] + +1. Procedure step +1. Procedure step + + + +## [Advanced troubleshooting and data collection] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/global-demonstration-template b/.github/projects/article-templates/global-demonstration-template new file mode 100644 index 0000000000..d28bae7a9a --- /dev/null +++ b/.github/projects/article-templates/global-demonstration-template @@ -0,0 +1,172 @@ +--- +title: "How [product or service] [solves a problem]" +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: get-started #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Demonstration: [verb] * [capability] * [product or service] * [scenario] + + + +[Introduce and explain the purpose of the article.] + + + +If you don't have a service subscription, create a free +trial account . . . + + + +## Prerequisites + + + +## Open [Cloud Shell, Azure CLI, or PowerShell] + + + +## [Demonstrate a solution to a problem] + + + +## What problem will we solve? + + + +## [Demonstration] + +[Introduce the demonstration.] + + + +## Clean up resources + + + +## Next step -or- Related content + +> [!div class="nextstepaction"] +> [Next sequential article title](link.md) + +-or- + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + \ No newline at end of file diff --git a/.github/projects/article-templates/guide-deployment-guide.yml b/.github/projects/article-templates/guide-deployment-guide.yml new file mode 100644 index 0000000000..b1945e5ce7 --- /dev/null +++ b/.github/projects/article-templates/guide-deployment-guide.yml @@ -0,0 +1,47 @@ +# guide: deployment-guide +name: Deployment guide +items: +- name: Deployment overview + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-overview-template" + required: yes + limit: 1 +- name: Prepare for deployment + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: yes + limit: 1 +- name: Deployment overview + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: yes + limit: 1 +- name: Deployment step 1...n + href: "/link-to: ms.topic: How-to" + required: yes + limit: none +- name: After deployment + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: no + limit: 1 +- name: Checklist + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-checklist-template" + required: no + limit: 1 +- name: Integration + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-integration-guide-template" + required: no + limit: 1 +- name: Troubleshooting + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-general-troubleshoot-template" + required: no + limit: 1 +- name: Best practices + href: "https:/review.learn.microsoft.com/help/patterns/level4/global-best-practices-template" + required: no + limit: 1 +- name: FAQ + href: "https:/review.learn.microsoft.com/help/patterns/level4/article-structured-faq" + required: no + limit: 1 +- name: Reference + href: "https:/review.learn.microsoft.com/help/contribute/reference-overview?branch=main" + required: no + limit: 1 \ No newline at end of file diff --git a/.github/projects/article-templates/guide-planning.yml b/.github/projects/article-templates/guide-planning.yml new file mode 100644 index 0000000000..e5dfec0abc --- /dev/null +++ b/.github/projects/article-templates/guide-planning.yml @@ -0,0 +1,25 @@ +# guide: planning +name: Plan __ +items: +- name: Plan __ + items: + - name: Plan __ + href: "https://review.learn.microsoft.com/en-us/help/patterns/level4/global-overview-template" + required: yes + limit: 1 + - name: Prerequisites + href: "https://review.learn.microsoft.com/en-us/help/patterns/level4/global-concept-template" # alternately, can use ms.topic: checklist + required: yes + limit: 0 + - name: Prerequisites + href: "https://review.learn.microsoft.com/en-us/help/patterns/level4/global-checklist-template" # alternately, can use ms.topic: concept-article + required: no + limit: 1 + - name: Considerations + href: "https://review.learn.microsoft.com/en-us/help/patterns/level4/global-concept-template" # alternately, can use ms.topic: checklist + required: yes + limit: 1 + - name: Considerations + href: "https://review.learn.microsoft.com/en-us/help/patterns/level4/global-checklist-template" # alternately, can use ms.topic: concept-article + required: no + limit: 1 \ No newline at end of file diff --git a/.github/projects/article-templates/guide-upgrade-and-migration.yml b/.github/projects/article-templates/guide-upgrade-and-migration.yml new file mode 100644 index 0000000000..6ec0c0caf4 --- /dev/null +++ b/.github/projects/article-templates/guide-upgrade-and-migration.yml @@ -0,0 +1,47 @@ +# guide: upgrade-and-migration +name: Upgrade or Migration guide +items: +- name: Overview + href: "https://review.learn.microsoft.com/help/patterns/level4/global-overview-template" + required: yes + limit: 1 +- name: Prerequisites + href: "https://review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: no + limit: 1 +- name: Methods + href: "https://review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: no + limit: 1 +- name: Resources + href: "https://review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: no + limit: 1 +- name: Assessment + href: "https://review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: no + limit: 1 +- name: Preupgrade or premigration tasks + href: "https://review.learn.microsoft.com/help/patterns/level4/global-how-to-template" + required: no + limit: 1 +- name: Migration step 1...n + href: "https://review.learn.microsoft.com/help/patterns/level4/global-how-to-template" + required: yes + limit: none +- name: Validation + href: "https://review.learn.microsoft.com/help/patterns/level4/global-how-to-template" + required: no + limit: 1 +- name: Post-upgrade or post-migration tasks + href: "https://review.learn.microsoft.com/help/patterns/level4/global-how-to-template" + required: no + limit: 1 +- name: What to expect after upgrade or migration + href: "https://review.learn.microsoft.com/help/patterns/level4/global-concept-template" + required: no + limit: 1 +- name: Troubleshooting + href: "https://review.learn.microsoft.com/help/patterns/level4/global-general-troubleshoot-template" + required: no + limit: 1 \ No newline at end of file diff --git a/.github/projects/article-templates/guide-waf-workloads.yml b/.github/projects/article-templates/guide-waf-workloads.yml new file mode 100644 index 0000000000..01cbeecd8b --- /dev/null +++ b/.github/projects/article-templates/guide-waf-workloads.yml @@ -0,0 +1,31 @@ +# guide: waf-workload +name: Workload name documentation +items: +- name: Quick links + href: index.yml #landing page template + required: yes + limit: 1 +- name: Get started + href: "help-content/patterns/level4/waf-get-started-template.md" + required: yes + limit: 1 +- name: Design methodology + href: "help-content/patterns/level4/waf-design-methodology-template.md" + required: yes + limit: 1 +- name: Design principles + href: "help-content/patterns/level4/waf-design-principles-template.md" + required: yes + limit: none +- name: Cross-cutting concerns + href: "help-content/patterns/level4/waf-cross-cutting-concerns-template.md" + required: yes + limit: 1 +- name: Architecture pattern + href: "help-content/patterns/level4/waf-architecture-pattern-template.md" + required: yes + limit: 1 +- name: Design areas + href: "help-content/patterns/level4/waf-design-areas-template.md" + required: yes + limit: 1 \ No newline at end of file diff --git a/.github/projects/article-templates/known-issues.md b/.github/projects/article-templates/known-issues.md new file mode 100644 index 0000000000..b0cdf0eb2d --- /dev/null +++ b/.github/projects/article-templates/known-issues.md @@ -0,0 +1,93 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: troubleshooting-known-issue #Don't change. +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Known issues: [product or service] + + + +[Introduce and explain the purpose of the article.] + + + +## [Issue] + + + +[Describe the issue.] + + + +### Prerequisites + + + +### Troubleshooting steps + + + +### Possible causes + + diff --git a/.github/projects/article-templates/problem-resolution.md b/.github/projects/article-templates/problem-resolution.md new file mode 100644 index 0000000000..66a307783d --- /dev/null +++ b/.github/projects/article-templates/problem-resolution.md @@ -0,0 +1,160 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: troubleshooting-problem-resolution #Don't change. +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# [Error message or key words that describe the problem] + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## Symptoms + + + + + +## Cause + + + +## Solution [number, if there are more than one] + +1. Procedure step +1. Procedure step + + + + + +## Determine the cause of the problem + + + +## Cause [number] + + + +### Solution [number, if there are more than one] + +1. Procedure step +1. Procedure step + + + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-best-practices.md b/.github/projects/article-templates/template-best-practices.md new file mode 100644 index 0000000000..e290966906 --- /dev/null +++ b/.github/projects/article-templates/template-best-practices.md @@ -0,0 +1,93 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: best-practice #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Best practices for [service or product] + + + +[Introduce and explain the purpose of the article.] + + + +## [Best practices section] + +[Introduce a best practices section.] + + + +## [Best practice] + +[Describe a best practice.] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-bicep-quickstart.md b/.github/projects/article-templates/template-bicep-quickstart.md new file mode 100644 index 0000000000..012a63eeac --- /dev/null +++ b/.github/projects/article-templates/template-bicep-quickstart.md @@ -0,0 +1,249 @@ +--- +title: #Required. The page title that's displayed in search results. Start with "Quickstart" and include "Bicep." +description: #Required. The article description that's displayed in search results. Include "quickstart." +author: #Required. Your GitHub user alias. Use correct capitalization. +ms.author: #Required. The Microsoft alias of the author. Optionally, a team alias. +ms.service: #Required. The approved service name. The service slug assigned by ACOM. +ms.topic: quickstart-bicep #Required; leave this attribute/value as-is. +ms.custom: #Required. Use "subject-bicepqs." +ms.date: #Required. The publish date in mm/dd/yyyy format. +--- + + + + + +# Quickstart: with Bicep +TODO: Add your heading + + + +[Introductory sentence] +TODO: Add your introductory sentence + +[!INCLUDE [About Bicep](/includes/resource-manager-quickstart-bicep-introduction.md)] +TODO: Update the path to the include file + + + +## Prerequisites + +- If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin. +- [Your prerequisites] + TODO: Add your prerequisites +- [Azure CLI prerequisites] + TODO: Add the Azure CLI prerequisites +- [Azure PowerShell prerequisites] + TODO: Add the Azure PowerShell prerequisites + + + +## Review the Bicep file + +The Bicep file used in this quickstart is from +[Azure Quickstart Templates](https://azure.microsoft.com/resources/templates/). + +[code-block-or-link-to-code] +TODO: Add your code or link + +The following Azure resources are defined in the Bicep file: + +- [Link to resource definition] +- [Link to resource definition] +- ... + +TODO: Add your resource definition links + +For more [product or service] Bicep samples, see +[Azure Quickstart Templates by resource types](https://azure.microsoft.com/resources/templates/?resourceType=Microsoft.&pageNumber=1&sort=Popular). +TODO: Add your link to samples + + + +## Deploy the Bicep file + +1. Save the Bicep file as `main.bicep` to your local computer. + +1. Deploy the Bicep file by using either Azure CLI or Azure PowerShell. + + [Azure CLI commands] + [Azure PowerShell commands] + +TODO: Add your commands + + + +## Review deployed resources + +[Azure CLI commands] +[Azure PowerShell commands] +TODO: Add your commands + + + +## Clean up resources + +[Instructions for cleaning up resources] +[Azure CLI commands] +[Azure PowerShell commands] +TODO: Add your instructions and commands + + + +## Next steps + +> [!div class="nextstepaction"] +> [Quickstart: ]() + +- [Links to related information] +TODO: Add your quickstart or related information links + + \ No newline at end of file diff --git a/.github/projects/article-templates/template-checklist.md b/.github/projects/article-templates/template-checklist.md new file mode 100644 index 0000000000..584c51624b --- /dev/null +++ b/.github/projects/article-templates/template-checklist.md @@ -0,0 +1,78 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: checklist #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Checklist for [product, service, or feature] + + + +[Introduce and explain the purpose of the article.] + + + +## [Checklist] + +[Insert a checklist.] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-concept.md b/.github/projects/article-templates/template-concept.md new file mode 100644 index 0000000000..a3258fa13d --- /dev/null +++ b/.github/projects/article-templates/template-concept.md @@ -0,0 +1,102 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: concept-article #Don't change. +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# [noun phrase] concept(s) + +or + +# [noun] overview + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## [Main idea] + +[Describe a main idea.] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-error-codes.md b/.github/projects/article-templates/template-error-codes.md new file mode 100644 index 0000000000..cb5996b0ca --- /dev/null +++ b/.github/projects/article-templates/template-error-codes.md @@ -0,0 +1,69 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: error-reference #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Error codes: [product, service, or feature] + + + +[Introduce a table that lists the error codes.] + + + +| Code | Error message | Details | +| --- | --- | --- | +| `code` | `message` | `details` | +| `code` | `message` | `details` | +| `code` | `message` | `details` | + + + + diff --git a/.github/projects/article-templates/template-feature-description.md b/.github/projects/article-templates/template-feature-description.md new file mode 100644 index 0000000000..e98ef1bf05 --- /dev/null +++ b/.github/projects/article-templates/template-feature-description.md @@ -0,0 +1,142 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: conceptual #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# [Feature] in [product or service] + + + +[Introduce and explain the purpose of the article.] + + + +## Use cases + +- [Use case] +- [Use case] + + + +## [Feature description] + + + +### Requirements + + + +### Considerations + + + +### Examples + + + +## Availability and pricing + +- [Link to regions where the feature is available] +- [Link to pricing information] + + + +## Limitations + +- [Limitation] +- [Limitation] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-get-started-guide.yml b/.github/projects/article-templates/template-get-started-guide.yml new file mode 100644 index 0000000000..484af048f4 --- /dev/null +++ b/.github/projects/article-templates/template-get-started-guide.yml @@ -0,0 +1,17 @@ +items: +- name: What is / + href: ../templates/template-overview.md +- name: Similar / comparison +- href: ../templates/template-product-comparison.md +- name: When to use / +- href: ../templates/template-concept.md +- name: / Set up +- href: ../templates/template-quickstart.md +- name: How to guide + href: ../templates/template-how-to-guide.md +- name: How to guide + href: ../templates/template-how-to-guide.md +- name: How to guide + href: ../templates/template-how-to-guide.md +- name: How to get support + href: ../templates/template-concept.md \ No newline at end of file diff --git a/.github/projects/article-templates/template-get-started.md b/.github/projects/article-templates/template-get-started.md new file mode 100644 index 0000000000..7e38002e2c --- /dev/null +++ b/.github/projects/article-templates/template-get-started.md @@ -0,0 +1,131 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: get-started #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Get started with [product or service] + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## [Table of stages] + + + +## [Stages] + + + +## [Who or what information] + + + +## Get help + + + +## Next step -or- Related content + +> [!div class="nextstepaction"] +> [Next sequential article title](link.md) + +-or- + +* [Related article title](link.md) +* [Related article title](link.md) +* [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-glossary.md b/.github/projects/article-templates/template-glossary.md new file mode 100644 index 0000000000..883e06c310 --- /dev/null +++ b/.github/projects/article-templates/template-glossary.md @@ -0,0 +1,93 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: glossary #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Glossary for [product or service] + + + +[Introduce and explain the purpose of the article.] + + + +## A -or- [range of letters] + + + +### [A term] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-how-to-guide.md b/.github/projects/article-templates/template-how-to-guide.md new file mode 100644 index 0000000000..7185b3434d --- /dev/null +++ b/.github/projects/article-templates/template-how-to-guide.md @@ -0,0 +1,125 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: how-to #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# "[verb] * [noun]" + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## "[verb] * [noun]" + +[Introduce the procedure.] + +1. Procedure step +1. Procedure step +1. Procedure step + + + +## Clean up resources + + + +## Next step -or- Related content + +> [!div class="nextstepaction"] +> [Next sequential article title](link.md) + +-or- + +* [Related article title](link.md) +* [Related article title](link.md) +* [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-install-setup-deploy.md b/.github/projects/article-templates/template-install-setup-deploy.md new file mode 100644 index 0000000000..8c6471a954 --- /dev/null +++ b/.github/projects/article-templates/template-install-setup-deploy.md @@ -0,0 +1,128 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: install-set-up-deploy #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Install/Set up/Deploy [product or service] + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## Methods + + + +## [Process steps] + + + +[Introduce a procedure and its role in completing the step.] + +1. Procedure step +1. Procedure step +1. Procedure step + +## Troubleshooting, validation, and/or FAQ + + + +## Next step -or- Related content + +> [!div class="nextstepaction"] +> [Next sequential article title](link.md) + +-or- + +* [Related article title](link.md) +* [Related article title](link.md) +* [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-integration-guide.md b/.github/projects/article-templates/template-integration-guide.md new file mode 100644 index 0000000000..0205d9b6ad --- /dev/null +++ b/.github/projects/article-templates/template-integration-guide.md @@ -0,0 +1,118 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: integration #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Integrate [product or service] with [product or service] + + + +[Introduce and explain the purpose of the article.] + + + +## Prerequisites + + + +## [Integration steps] + + + +## Test the integration + + + +## Next step -or- Related content + +> [!div class="nextstepaction"] +> [Next sequential article title](link.md) + +-or- + +* [Related article title](link.md) +* [Related article title](link.md) +* [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-limits-and-quotas.md b/.github/projects/article-templates/template-limits-and-quotas.md new file mode 100644 index 0000000000..138e7c1918 --- /dev/null +++ b/.github/projects/article-templates/template-limits-and-quotas.md @@ -0,0 +1,92 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: limits-and-quotas #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# [product or service] limits and quotas + + + +[Introduce and explain the purpose of the article.] + + + +## [General information about limits and quotas] + + + +## [Limits and quotas table] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-managed-identities.md b/.github/projects/article-templates/template-managed-identities.md new file mode 100644 index 0000000000..6ad6b94761 --- /dev/null +++ b/.github/projects/article-templates/template-managed-identities.md @@ -0,0 +1,176 @@ +--- +title: Use managed identities in [Service name] | Microsoft Docs #Required; page title is displayed in search results. +description: Learn how to use managed identities with [Service name] using the Azure portal, CLI, PowerShell, and ARM template. #Required; article description that is displayed in search results. Update depending on which options you use. +author: #Required; your GitHub user alias, with correct capitalization. +ms.author: #Required; microsoft alias of author; optional team alias. +ms.service: #Required; Select service from approved list. +ms.topic: how-to #Required. +ms.date: #Required; mm/dd/yyyy format. +--- + + +# How to use managed identities with [Service name] +TODO: Add H1 headline. + + + +This article shows you how to use managed identities with a [Service name] instance. +TODO: Add introduction. + + + +## Prerequisites + +- [Prerequisite 1] +- [Prerequisite 2] +- [Prerequisite n] + +TODO: Add prerequisites section, if needed. + + + +## Create an instance of [service name] with a system assigned managed identity + +# [Portal](#tab/azure-portal) + +# [Azure PowerShell](#tab/azure-powershell) + +# [Azure CLI](#tab/azure-cli) + +# [ARM template](#tab/azure-resource-manager) + +--- + +TODO: Add Create an instance section with tabbed conceptual options. + + + +## Assign a user-assigned managed identity to a service instance + +# [Portal](#tab/azure-portal) + +# [Azure PowerShell](#tab/azure-powershell) + +# [Azure CLI](#tab/azure-cli) + +# [ARM template](#tab/azure-resource-manager) + +--- + +TODO: Add Assign identity section with tabbed conceptual options. + + + +## Supported scenarios using managed identities + +### User assigned managed identities + +### System assigned managed identities + +TODO: Describe supported scenarios. + + + +### Grant access to a managed identity +TODO: Add grant access section. + + + + + +## Clean up steps +TODO: Add clean up steps. + + + +## Next steps + +Learn more about managed identities for Azure resources: + +- [What are managed identities for Azure resources?](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) + +TODO: Add Next steps. + + diff --git a/.github/projects/article-templates/template-move-across-regions.md b/.github/projects/article-templates/template-move-across-regions.md new file mode 100644 index 0000000000..e8132454e0 --- /dev/null +++ b/.github/projects/article-templates/template-move-across-regions.md @@ -0,0 +1,178 @@ +--- +title: #Required; page title is displayed in search results. Format is: Relocation guidance for [service-name] +description: #Required; article description that is displayed in search results. Include the words "relocate", and "region" in the description. +author: #Required; your GitHub user alias, with correct capitalization. +ms.author: #Required; microsoft alias of author; optional team alias. +ms.service: #Required; service per approved list. slug assigned by ACOM. +ms.topic: how-to #Required; leave this attribute/value as-is. +ms.date: #Required; mm/dd/yyyy format. +ms.custom: + - subject-moving-resources + - subject-relocation #Required; leave this attribute/value as-is. + +--- + + + +#Customer intent: As a < type of user >, I want < what? > so that < why? >. +TODO: Add customer intent statement. + + + +# [H1 heading] +TODO: Add your heading. + + + +[Add your introductory paragraph] +TODO: Add your introductory paragraph + + + +## Prerequisites +TODO: Add the Prerequisites section. + + + + +## Considerations for Service Endpoints +TODO: Add the Considerations for Service Endpoints section + + + +## Consideration for Private Endpoints +TODO: Add the Consideration for Private Endpoints + + + +## Prepare +TODO: Add the Prepare section. + + + +## Modify the template +TODO: Add the Modify the template section. + + + + +## Redeploy +TODO: Add the Redeploy section. + + + +## Redeploy with data +TODO: Add the Redeploy section. + + + +## Verify +TODO: Add the Verify section. + + + +## Commit +TODO: Add this section, if necessary. + + + +## Discard target resources +TODO: Add this section, if desired. + + + +## Clean up source resources +TODO: Add the Clean up resources section. + + + +## Next steps +TODO: Add your next steps. + + diff --git a/.github/projects/article-templates/template-overview.md b/.github/projects/article-templates/template-overview.md new file mode 100644 index 0000000000..670f773e76 --- /dev/null +++ b/.github/projects/article-templates/template-overview.md @@ -0,0 +1,80 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: overview #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# What is [product or service]? + + + +[Introduce and explain the purpose of the article.] + + + +## [Feature section] + +[Introduce a section that describes a feature.] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-partner-tools.md b/.github/projects/article-templates/template-partner-tools.md new file mode 100644 index 0000000000..1856044dc7 --- /dev/null +++ b/.github/projects/article-templates/template-partner-tools.md @@ -0,0 +1,96 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: partner-tools #Don't change +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# [product] [feature] partners + +-or- + +# [product] partners for [feature] + + + +[Introduce and explain the purpose of the article.] + + + +## [category of tools] + +[Introduce table as needed.] + +| Partner | Description | Links | Regions (as needed) | +| ------- | ----------- | ----- | ------------------- | + +-or- + +## [partner name] + +[Describe partner tools.] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-product-comparison.md b/.github/projects/article-templates/template-product-comparison.md new file mode 100644 index 0000000000..83feb1ca60 --- /dev/null +++ b/.github/projects/article-templates/template-product-comparison.md @@ -0,0 +1,114 @@ +--- +title: [Follow SEO guidance at +https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title] + -or- Choose between [service 1] and [service 2]" +description: "[Article description]." +author: [your GitHub alias] +ms.author: [your Microsoft alias or a team alias] +ms.service: [the approved service name] +ms.topic: product-comparison #Don't change in the template. +ms.date: [mm/dd/yyyy] + +#customer intent: As a , I want so that . + +--- + + + +# Choose a(n) [service category] + +-or- + +# Choose between [service 1] and [service 2] + + + +[Introduce and explain the purpose of the article.] + + + +## Choose a candidate service + + + +## [Criterion] + + + +## Related content + +- [Related article title](link.md) +- [Related article title](link.md) +- [Related article title](link.md) + + + + diff --git a/.github/projects/article-templates/template-quickstart-resource-manager.md b/.github/projects/article-templates/template-quickstart-resource-manager.md new file mode 100644 index 0000000000..1be6fd9897 --- /dev/null +++ b/.github/projects/article-templates/template-quickstart-resource-manager.md @@ -0,0 +1,152 @@ +--- +title: Create a {service name} by using Azure Resource Manager template (ARM template) +description: Learn how to create an Azure {service name} by using Azure Resource Manager template (ARM template). +services: azure-resource-manager +ms.service: azure-resource-manager +author: your-github-account-name +ms.author: your-microsoft-alias +ms.topic: quickstart-arm #Required; leave this attribute/value as-is. +ms.custom: subject-armqs +ms.date: MM/DD/YYYY + +# Customer intent: As a cloud administrator, I want a quick method to deploy an Azure resource for production environments or to evaluate the service's functionality. +--- + + + +# Quickstart: The H1 heading must include the words ARM template + + + +This quickstart describes how to use an Azure Resource Manager template (ARM template) to create +{service name}. + + + +[!INCLUDE [About Azure Resource Manager](../../includes/resource-manager-quickstart-introduction.md)] + + + +If your environment meets the prerequisites and you're familiar with using ARM templates, select the +**Deploy to Azure** button. The template will open in the Azure portal. + +:::image type="content" source="~/articles/reusable-content/ce-skilling/azure/media/template-deployments/deploy-to-azure-button.svg" alt-text="Button to deploy the Resource Manager template to Azure." border="false" link="https://portal.azure.com/#create/Microsoft.Template/uri/"::: + +## Prerequisites + + + +If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin. + +## Review the template + + + +The template used in this quickstart is from [Azure Quickstart Templates](https://azure.microsoft.com/resources/templates/). + + + +:::code language="json" source="~/quickstart-templates/