68 lines
3.9 KiB
Markdown
68 lines
3.9 KiB
Markdown
# 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](Policies.md#installer-types) 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](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:
|
|
|
|
```powershell
|
|
winget validate --manifest <path-to-manifest>
|
|
```
|
|
|
|
10. Test the install locally:
|
|
|
|
```powershell
|
|
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).
|
|
|
|
11. If possible, test in Windows Sandbox with [`Tools\SandboxTest.ps1`](tools/SandboxTest.md).
|
|
12. 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.
|
|
13. After you submit the PR, watch for validation labels and review [ValidationFailureGuide.md](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
|
|
|
|
```mermaid
|
|
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]
|
|
```
|