winget-pkgs/.github/copilot-instructions.md

Copilot Instructions for winget-pkgs

Repository Overview

This is the Windows Package Manager (WinGet) community repository — a manifest-only repo containing ~415,000+ YAML files describing how to install Windows applications via winget. There is no application source code here. The tooling is PowerShell scripts in Tools/.

⚠️ Critical Performance Rule

Never recursively scan or search the manifests/ directory. It contains hundreds of thousands of files and will cause severe performance issues. Only search within the specific package folder being modified (e.g., manifests/m/Microsoft/WindowsTerminal/).

Manifest Structure

Each package version lives in manifests/<first-letter>/<Publisher>/<Package>/<Version>/ and requires three files:

File	ManifestType	Purpose
<Id>.yaml	version	Version metadata, links other files
<Id>.installer.yaml	installer	Installer URLs, SHA256 hashes, architecture, installer type
<Id>.locale.en-US.yaml	defaultLocale	Package name, publisher, description, license

Additional <Id>.locale.<tag>.yaml files provide optional translations.

Key rules:

• File and folder names are case-sensitive and must match the PackageIdentifier exactly
• The version folder name must match PackageVersion exactly
• The first directory under manifests/ is the lowercase first letter of the publisher
• Each YAML file includes a # yaml-language-server: $schema=... comment pointing to its JSON schema
• Recommended schema version: 1.12.0 (1.10.0 also accepted)
• Supported installer types: MSIX, MSI, APPX, EXE, and font files only — no scripts

PR Conventions

• Each PR must modify exactly one package (one manifest set for one version)
• PRs to manifests/ trigger an Azure DevOps validation pipeline that runs file validation, URL scanning, SmartScreen checks, manifest policy checks, installation verification, and installer metadata validation
• PRs are auto-merged when the Validation-Completed label is applied (squash merge)
• Contributors must sign the Microsoft CLA

Issues and Pull Requests

• Before filing an issue, search existing open and closed issues for duplicates.
• Use the GitHub issue forms in .github/ISSUE_TEMPLATE/; do not file a blank issue unless a maintainer explicitly asks for one.
• Use package_issue.yml for package behavior problems, package_request.yml for new package requests, update_request.yml for version update requests, and feature_request.yml for repository or process improvements.
• Do not file WinGet client issues here; use microsoft/winget-cli for client behavior.
• Keep issue bodies concise and evidence-based. Do not paste large speculative patches into issue bodies; open a pull request or link a branch when manifest changes are available.
• Before opening a pull request, review CONTRIBUTING.md, follow the PR template, keep the change to exactly one package, and summarize validation performed.

Validation and Testing Commands

Validate a manifest locally:

winget validate --manifest <path-to-version-folder>

Test installation locally:

winget settings --enable LocalManifestFiles
winget install --manifest <path-to-version-folder>

Test in Windows Sandbox (preferred — isolated environment):

.\Tools\SandboxTest.ps1 <path-to-version-folder>

Tooling

Tool	Purpose
Tools/YamlCreate.ps1	Interactive manifest creation/update helper
Tools/SandboxTest.ps1	Test manifests in Windows Sandbox
Tools/PRTest.ps1	PR testing utilities
Tools/Modules/YamlCreate/	PowerShell module supporting YamlCreate

Manifest creation is best done with winget-create:

wingetcreate new <InstallerURL>       # New package
wingetcreate update <PackageId>       # Update existing package

CI/CD

• GitHub Actions: PSScriptAnalyzer (lints *.ps1/*.psm1 on PR/push) and spell checking
• Azure DevOps: Validation and publish pipelines for manifest PRs (defined in DevOpsPipelineDefinitions/)

Run PSScriptAnalyzer locally on PowerShell scripts:

Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
Get-ChildItem -Recurse -Filter *.ps1 | Invoke-ScriptAnalyzer

Code Style

• YAML: 2-space indentation, CRLF line endings, UTF-8, trailing whitespace trimmed
• YAML fields are PascalCased and must not be duplicated
• PowerShell: follows PSScriptAnalyzer rules
• See .editorconfig for full formatting rules