Skip to content

Latest commit

 

History

History
80 lines (62 loc) · 5.19 KB

FirstContribution.md

File metadata and controls

80 lines (62 loc) · 5.19 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.
  4. Check whether Microsoft's Contributor License Agreement (CLA) bot asks you to complete the agreement. Follow its instructions using your own account; a successful WinGet validation does not clear a CLA-related merge block.

Contributor License Agreement (CLA)

Most Microsoft contributions require a Contributor License Agreement. This is separate from the manifest's validation checks: a PR may pass the validation pipeline and still be blocked from merging until the CLA requirement is satisfied.

After submitting a PR, read the Microsoft CLA bot's message or status check and follow its linked instructions. The contributor must personally complete any required agreement; a generic acknowledgement comment on the PR does not replace the official CLA process. Microsoft's repository contribution guidance explains the requirement and notes that the agreement generally needs to be completed only once for Microsoft repositories using the same CLA.

Once the CLA requirement is met, continue responding to validation and maintainer review feedback as usual.

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]
    R --> S{CLA action requested<br/>by Microsoft bot?}
    S -- Yes --> T[Complete the official<br/>Microsoft CLA process]
    S -- No --> U[Continue with validation<br/>and maintainer review]
    T --> U
Loading