Skip to content

FirstContribution.md

Latest commit

 

History

History
67 lines (53 loc) · 3.87 KB

FirstContribution.md

File metadata and controls

67 lines (53 loc) · 3.87 KB

First-Time Contributor Checklist

Use this checklist before you open your first manifest PR to microsoft/winget-pkgs. It focuses on the repository rules that most often cause first-pass validation failures.

Pre-submit checklist

  1. Confirm there is not already an open PR for the same package version.

  2. Keep the PR to one package version only. In this repository, that means one multi-file manifest set for a single PackageIdentifier and PackageVersion.

  3. Keep the PR to manifest files only. If you also need to update spelling files, README.md, doc/, tooling, or any other non-manifest file, submit those changes in a separate PR.

  4. Use a supported installer type and make sure the installer can run unattended.

  5. Use a multi-file manifest set. Singleton manifests are not allowed in the community repository.

  6. Add schema headers to every manifest file, including the # yaml-language-server: $schema=... comment at the top of each file.

  7. Use the latest manifest version supported by the repository. See doc\manifest\README.md for the current schema versions.

  8. Use a stable, version-specific installer URL from an official source whenever possible.

  9. Validate the manifest locally:

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

  10. Test the install locally:

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

Note

winget settings --enable LocalManifestFiles requires elevation (run as administrator). On enterprise-managed devices, Group Policy may also block this setting. If you cannot enable local manifests, use Windows Sandbox with Tools\SandboxTest.ps1 instead (step 11).

  1. If possible, test in Windows Sandbox with Tools\SandboxTest.ps1.
  2. If your PR is a routine manifest submission, you do not need a separate issue first. Open an issue when you are proposing a repo change, discussing a policy/spec question, or reporting a broader problem.
  3. After you submit the PR, watch for validation labels and review ValidationFailureGuide.md if the bot reports a problem.

One PR change means one package version

The repository enforces one PR change strictly:

  • Allowed: one package version represented by its full multi-file manifest set
  • Not allowed: two versions of the same package in one PR
  • Not allowed: a manifest submission plus unrelated manifest changes
  • Not allowed: a manifest submission plus non-manifest files such as spelling updates, README.md, doc/ content, or tooling changes

If you discover a documentation, spelling, or tooling fix while preparing a manifest, finish the manifest PR first and submit the repo/documentation change as a separate PR.

First-time contributor decision tree

flowchart TD
    A[Start a manifest<br/>contribution] --> B{Existing PR for this<br/>package version?}
    B -- Yes --> C[Do not open<br/>another PR]
    B -- No --> D{Exactly one package<br/>version in this PR?}
    D -- No --> E[Split the work into<br/>separate PRs]
    D -- Yes --> F{Any non-manifest files<br/>in this PR?}
    F -- Yes --> G[Move non-manifest changes<br/>to a separate PR]
    F -- No --> H{Stable and version-specific<br/>installer URL?}
    H -- No --> I[Use a stable official<br/>release URL]
    H -- Yes --> J{Installer can run<br/>unattended?}
    J -- No --> K[Fix installer type,<br/>switches, or dependencies]
    J -- Yes --> L[Run winget validate<br/>--manifest <path>]
    L --> M{Validation<br/>succeeded?}
    M -- No --> N[Fix manifest issues<br/>and validate again]
    M -- Yes --> O[Run winget install<br/>--manifest <path>]
    O --> P{Install test<br/>succeeded?}
    P -- No --> Q[Fix installer behavior,<br/>URL, or metadata]
    P -- Yes --> R[Submit the PR and<br/>monitor labels]
Loading