Merge remote-tracking branch 'upstream/main' into Specifications

.configurations/configuration.dsc.yaml

@@ -0,0 +1,102 @@
+# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
+
+properties:
+  resources:
+    ########################################################################
+    # Section: Install Git
+    ########################################################################
+    - resource: Microsoft.WinGet.DSC/WinGetPackage
+      id: install-git
+      directives:
+        description: Install Git # Although the user probably already has git installed, it's possible that they don't
+        allowPrerelease: true
+      settings:
+        id: Git.Git
+        source: winget
+        Ensure: Present
+    - resource: Microsoft.WinGet.DSC/WinGetPackage
+      dependsOn:
+        - install-git
+      id: install-github-cli
+      directives:
+        description: Install GitHub CLI
+        allowPrerelease: true
+        securityContext: elevated
+      settings:
+        id: GitHub.cli
+        source: winget
+        Ensure: Present
+    ########################################################################
+    # Section: Configure Git Remotes
+    ########################################################################
+    - resource: GitDSC/GitRemote
+      id: add-microsoft-upstream
+      directives:
+        description: Add microsoft/winget-dsc as the upstream remote
+        allowPrerelease: true
+      settings:
+        ProjectDirectory: '${WinGetConfigRoot}\..'
+        RemoteName: upstream
+        RemoteUrl: https://github.com/microsoft/winget-pkgs.git
+    ########################################################################
+    # Section: Install VS-Code
+    ########################################################################
+    - resource: Microsoft.WinGet.DSC/WinGetPackage
+      id: install-vs-code
+      directives:
+        description: Install Microsoft Visual Studio Code
+        allowPrerelease: true
+      settings:
+        id: Microsoft.VisualStudioCode
+        source: winget
+        Ensure: Present
+    - resource: Microsoft.VSCode.Dsc/VSCodeExtension
+      id: install_vscode-yaml
+      dependsOn:
+        - install-vs-code
+      directives:
+        description: Install YAML extension for VSCode
+        allowPrerelease: true
+      settings:
+        Name: redhat.vscode-yaml
+        Exist: true
+    - resource: Microsoft.VSCode.Dsc/VSCodeExtension
+      id: install_editorconfig.editorconfig
+      dependsOn:
+        - install-vs-code
+      directives:
+        description: Install EditorConfig extension for VSCode
+        allowPrerelease: true
+      settings:
+        Name: EditorConfig.EditorConfig
+        Exist: true
+    - resource: Microsoft.VSCode.Dsc/VSCodeExtension
+      id: install_ms-vscode.powershell
+      dependsOn:
+        - install-vs-code
+      directives:
+        description: Install PowerShell extension for VSCode
+        allowPrerelease: true
+      settings:
+        Name: ms-vscode.powershell
+        Exist: true
+    ########################################################################
+    # Section: Install PowerShell Modules
+    ########################################################################
+    - resource: PowerShellModule/PSModuleResource
+      id: install-pester
+      directives:
+        description: Install Pester module
+        allowPrerelease: true
+      settings:
+        Module_Name: Pester
+        Ensure: Present
+    - resource: PowerShellModule/PSModuleResource
+      id: install-psscriptanalyzer
+      directives:
+        description: Install PSScriptAnalyzer module
+        allowPrerelease: true
+      settings:
+        Module_Name: PSScriptAnalyzer
+        Ensure: Present
+  configurationVersion: 0.2.0

.github/actions/spelling/advice.md

@@ -2,6 +2,7 @@
 <details><summary>If the flagged items are :exploding_head: false positives</summary>
 
 If items relate to a ...
+
 * binary file (or some other file you wouldn't want to check at all).
 
   Please add a file path to the `excludes.txt` file matching the containing file.

.github/actions/spelling/allow.txt

@@ -11,6 +11,7 @@ codeowners
 github
 https
 Icm
+markdownlint
 microsoft
 msftbot
 numpy
@@ -38,3 +39,8 @@ Windo
 ELSPROBLEMS
 requ
 PDevice
+whatif
+pscustomobject
+VGpu
+wildcards
+worktree

.github/actions/spelling/candidate.patterns

@@ -509,12 +509,7 @@ customObjectInstantitationMethod
 
 # version suffix <word>v#
 (?:(?<=[A-Z]{2})V|(?<=[a-z]{2}|[A-Z]{2})v)\d+(?:\b|(?=[a-zA-Z_]))
-# Compiler flags (Scala)
-(?:^|[\t ,>"'`=(])-J-[DPWXY](?=[A-Z]{2,}|[A-Z][a-z]|[a-z]{2,})
-# Compiler flags
-(?:^|[\t ,"'`=(])-[DPWXYLlf](?=[A-Z]{2,}|[A-Z][a-z]|[a-z]{2,})
-# Compiler flags (linker)
-,-B
+
 # curl arguments
 \b(?:\\n|)curl(?:\s+-[a-zA-Z]{1,2}\b)*(?:\s+-[a-zA-Z]{3,})(?:\s+-[a-zA-Z]+)*
 # set arguments

.github/actions/spelling/expect/generic_terms.txt

@@ -1,16 +1,23 @@
-wildcards
-ssh
+AKV
 Amd
-usr
-screenshots
+Authenticode
+automerge
 currentstate
+esrp
+gtm
+msft
+NPH
+Peet
+rfc
+screenshots
 Scrollbars
 Searchbox
-VGpu
-versioning
-worktree
+SFP
+Signtool
 sortby
-msft
-automerge
+ssh
+usr
+versioning
+VGpu
 pnp
 RTX

.github/actions/spelling/expect/software.txt

@@ -2,7 +2,6 @@ vscode
 Linux
 dotnet
 dotnettool
-cspell
 NUnit
 reportgenerator
-Toolpackage
+markdownlint

.github/actions/spelling/patterns.txt

@@ -68,3 +68,6 @@ name\:\s+.+$
 
 # Commit Hashes
 [0-9a-f]{40}
+
+# Github User Content
+/[-a-z0-9]+\.githubusercontent\.com/[-a-zA-Z0-9?&=_\/.]*

.github/workflows/markdownLint.yaml

@@ -0,0 +1,35 @@
+name: Markdown Lint
+
+on:
+  push:
+    branches:
+      - '**'
+      - '!main'
+    tags-ignore:
+      - '**'
+  pull_request_target:
+    branches:
+      - '**'
+    tags-ignore:
+      - '**'
+    types:
+      - 'opened'
+      - 'reopened'
+      - 'synchronize'
+
+jobs:
+  lint:
+    name: Check Markdown linting
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: tj-actions/changed-files@v45
+      id: changed-files
+      with:
+        files: '**/*.md'
+    - uses: DavidAnson/markdownlint-cli2-action@v17
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-files.outputs.all_changed_files }}

.github/workflows/spellCheck.yaml

@@ -77,11 +77,11 @@ jobs:
           use_magic_file: 1
           extra_dictionary_limit: 10
           extra_dictionaries:
-            https://github.com/streetsidesoftware/cspell-dicts/raw/098e323325a389a5d1cebcd7770807b9d11d0a17/dictionaries/software-terms/src/software-terms.txt
+            https://raw.githubusercontent.com/streetsidesoftware/cspell-dicts/098e323325a389a5d1cebcd7770807b9d11d0a17/dictionaries/software-terms/src/software-terms.txt
             https://raw.githubusercontent.com/streetsidesoftware/cspell-dicts/098e323325a389a5d1cebcd7770807b9d11d0a17/dictionaries/filetypes/src/filetypes.txt
             https://raw.githubusercontent.com/streetsidesoftware/cspell-dicts/098e323325a389a5d1cebcd7770807b9d11d0a17/dictionaries/powershell/src/powershell.txt
             https://raw.githubusercontent.com/streetsidesoftware/cspell-dicts/098e323325a389a5d1cebcd7770807b9d11d0a17/dictionaries/win32/src/generator/win32.txt
-            https://github.com/streetsidesoftware/cspell-dicts/raw/098e323325a389a5d1cebcd7770807b9d11d0a17/dictionaries/python/src/common_packages.txt
+            https://raw.githubusercontent.com/streetsidesoftware/cspell-dicts/098e323325a389a5d1cebcd7770807b9d11d0a17/dictionaries/python/src/common_packages.txt
           check_extra_dictionaries: ''
 
   comment-push:

.markdownlint-cli2.yaml

@@ -0,0 +1,11 @@
+globs:
+  - "**/*.md"
+
+noProgress: true
+
+# Show found files on stdout (only valid at root)
+showFound: true
+
+ignores:
+  - "PRIVACY.md"
+  - ".github/*.md"

.markdownlint.yaml

@@ -0,0 +1,35 @@
+# Default state for all rules
+default: true
+
+# Path to configuration file to extend
+extends: null
+
+MD007:
+  # Spaces for indent
+  indent: 4
+  # Whether to indent the first level of the list
+  start_indented: false
+  # Spaces for first level indent (when start_indented is set)
+  start_indent: 2
+
+# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md013.md
+MD013:
+  # Number of characters
+  line_length: 500
+  # Number of characters for headings
+  heading_line_length: 120
+  # Number of characters for code blocks
+  code_block_line_length: 500
+  # Include code blocks
+  code_blocks: true
+  # Include tables
+  tables: true
+  # Include headings
+  headings: true
+  # Strict length checking
+  strict: false
+  # Stern length checking
+  stern: false
+
+# MD025/single-title : Help examples contain metadata
+MD025: false

.vscode/extensions.json

@@ -1,6 +1,8 @@
 {
     "recommendations": [
         "redhat.vscode-yaml",
-        "EditorConfig.EditorConfig"
+        "EditorConfig.EditorConfig",
+        "ms-vscode.powershell",
+        "davidanson.vscode-markdownlint"
     ]
 }

CONTRIBUTING.md

@@ -8,7 +8,9 @@ The Windows Package Manager team is active in this GitHub Repository. In fact, w
 
 When the team finds issues we file them in the repository. When we propose new ideas or think-up new features, we file new feature requests. When we work on fixes or features, we create branches and work on those improvements. And when PRs are reviewed, we review in public - including all the good, the bad, and the ugly parts.
 
-The point of doing all this work in public is to ensure that we are holding ourselves to a high degree of transparency, and so that the community sees that we apply the same processes and hold ourselves to the same quality-bar as we do to community-submitted issues and PRs. We also want to make sure that we expose our team culture and "tribal knowledge" that is inherent in any closely-knit team, which often contains considerable value to those new to the project who are trying to figure out "why the heck does this thing look/work like this???"
+The point of doing all this work in public is to ensure that we are holding ourselves to a high degree of transparency, and so that the community sees that we apply the same processes and hold ourselves to the same quality-bar as we do to community-submitted issues and PRs.
+
+We also want to make sure that we expose our team culture and "tribal knowledge" that is inherent in any closely-knit team, which often contains considerable value to those new to the project who are trying to figure out "why the heck does this thing look/work like this???"
 
 ### Repository Bot
 
@@ -21,6 +23,7 @@ We drive the bot by tagging issues with specific labels which cause the bot engi
 Therefore, if you do file issues, or create PRs, please keep an eye on your GitHub notifications. If you do not respond to requests for information, your issues/PRs may be closed automatically.
 
 ---
+
 ## Reporting Security Issues
 
 **Please do not report security vulnerabilities through public GitHub issues.** Instead, please report them to the Microsoft Security Response Center (MSRC). See [SECURITY.md](./SECURITY.md) for more information.
@@ -109,14 +112,30 @@ Once the team have approved an issue/spec, development can proceed. If no develo
 
 ### Fork, Clone, Branch and Create your PR
 
-Once you've discussed your proposed feature/fix/etc. with a team member, and you've agreed an approach or a spec has been written and approved, it's time to start development:
+Once you've discussed your proposed feature/fix/etc. with a team member, and you've agreed an approach or a spec has been written and approved, it's time to start development. There are two flows you can follow depending on the proposed feature or fix.
+
+If you're feature (or module) has not yet been created, follow these steps:
+
+1. Fork the repository if you haven't already.
+2. Clone your fork locally.
+3. Open a PowerShell terminal session and execute: `.\utilities\tools\New-DscResourceModule.ps1 -DscResourceModule '<moduleName>' -Description 'DSC Resource for <description>'`
+4. Work on your changes and write tests.
+5. Build and test to see if it works.
+6. Create & push a feature branch.
+7. Create a [Draft Pull Request (PR)](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
+8. If you are finished with your changes and you want a review, change the state.
+
+> [!TIP]
+> Don't forget to add the `DscResourcesToExport` and `Tags`.
+
+When you are working on a fix or you want to add additional features to an existing module, you can follow the below steps:
 
 1. Fork the repository if you haven't already.
-1. Clone your fork locally.
-1. Create & push a feature branch.
-1. Create a [Draft Pull Request (PR)](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
-1. Work on your changes.
-1. Build and see if it works.
+2. Clone your fork locally.
+3. Work on your fix or feature, and _optionally_ write tests
+4. Build and test to see if it works.
+5. Create & push a feature branch.
+6. Create a [Pull Request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) when you are finished with your changes
 
 ### Testing
 
@@ -126,7 +145,8 @@ Testing is a key component in the development workflow.
 
 When you'd like the team to take a look, (even if the work is not yet fully-complete), mark the Draft PR as 'Ready For Review' so that the team can review your work and provide comments, suggestions, and request changes. It may take several cycles, but the end result will be solid, testable, conformant code that is safe for us to merge.
 
-> ⚠ Remember: **changes you make may affect both the Windows Package Manager and the schema support implemented in our validation pipelines!** Because of this, we will treat community PR's with the same level of scrutiny and rigor as commits submitted to the official Windows source by team members and partners.
+> [!CAUTION]
+> Remember: **changes you make may affect both the Windows Package Manager and the schema support implemented in our validation pipelines!** Because of this, we will treat community PR's with the same level of scrutiny and rigor as commits submitted to the official Windows source by team members and partners.
 
 ### Merge
 

SECURITY.md

@@ -1,6 +1,6 @@
 <!-- BEGIN MICROSOFT SECURITY.MD V0.0.9 BLOCK -->
 
-## Security
+# Security
 
 Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet) and [Xamarin](https://github.com/xamarin).
 
@@ -18,13 +18,13 @@ You should receive a response within 24 hours. If for some reason you do not, pl
 
 Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
 
-  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
-  * Full paths of source file(s) related to the manifestation of the issue
-  * The location of the affected source code (tag/branch/commit or direct URL)
-  * Any special configuration required to reproduce the issue
-  * Step-by-step instructions to reproduce the issue
-  * Proof-of-concept or exploit code (if possible)
-  * Impact of the issue, including how an attacker might exploit the issue
+* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+* Full paths of source file(s) related to the manifestation of the issue
+* The location of the affected source code (tag/branch/commit or direct URL)
+* Any special configuration required to reproduce the issue
+* Step-by-step instructions to reproduce the issue
+* Proof-of-concept or exploit code (if possible)
+* Impact of the issue, including how an attacker might exploit the issue
 
 This information will help us triage your report more quickly.