Demitrius NelonandCopilot
640ef9b40c
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
97 lines
4.5 KiB
Markdown
97 lines
4.5 KiB
Markdown
# 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:
|
|
```powershell
|
|
winget validate --manifest <path-to-version-folder>
|
|
```
|
|
|
|
Test installation locally:
|
|
```powershell
|
|
winget settings --enable LocalManifestFiles
|
|
winget install --manifest <path-to-version-folder>
|
|
```
|
|
|
|
Test in Windows Sandbox (preferred — isolated environment):
|
|
```powershell
|
|
.\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](https://github.com/microsoft/winget-create):
|
|
```powershell
|
|
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:
|
|
```powershell
|
|
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
|