First, we want to say thank you. Your contribution is highly valued. And we appreciate the time you have taken to get here and read this document. Let's start out with a few definitions to help you understand our vocabulary.
Manifests are the YAML files in this repository containing the metadata used by the Windows Package Manager to install and upgrade software on Windows 10. There are hundreds of these files partitioned under the manifests directory. We've had to partition the directory structure so you don't have to scroll as much in the GitHub.com site when you are looking for a manifest.
Think of a package as an application or a program. We use a "PackageIdentifier" to represent a unique package. These are generally in the form of Publisher.Package. Sometimes you might see additional values separated by a second period. We will explain why a little bit later.
Package versions are associated with a specific release. In some cases you will see a perfectly formed semantic version number, and in other cases you might see something different. These may be date driven, or they might have other characters with some package specific meaning. The YAML key for a package version is "PackageVersion".
Once you have determined the "PackageIdentifier" and the "PackageVersion" it is possible to know the proper location for the manifest. We will use Microsoft Windows Terminal version 1.6.10571.0 for our example.
manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0
The partition directory is determined by taking the first letter from the "PackageIdentifier" in lower case. The next directory must match the first segment of the "PackageIdentifier" (case sensitive) up to the first period. This pattern continues until a directory has been created for each section of the "PackageIdentifier" (case sensitive) separated by a period. The last directory must match the "PackageVersion".
Before you invest the time to generate and submit a manifest, you should check to see if the package already exists. Start out with winget search package. If that doesn't yield anything, try a quick search using the search box in the top left corner of GitHub for the package "In this repository". If you still don't find anything, finally check to see if there is already a PR for the package by putting the package in the filters box, and be sure to remove the "is:pr is:open" filters.
You should take a look at our v1.0 manifest specification. Don't worry. If this is starting to look too complicated you can create a new Issue and select Package Request/Submission 👀.
The multi-file manifest is the preferred method for building manifests. The mimimum required files are a version file, a defaultLocale file and an installer file.
Once you have package in mind that doesn't already exist in the repository, you can now start creating your package manifest. We recommend using the Windows Package Manager Manifest Creator (a.k.a Winget-Create) to help you generate your manifest. Winget-Create is a command line tool that will prompt you for relevant metadata related to your package. Once you are done, Winget-Create will validate your manifest to verify that it is correct and allow you to submit your newly-created manifest directly to the winget-pkgs repository by linking your GitHub account. Alternatively, you can use the YamlCreate.ps1 Script. More information on using YamlCreate is found in the script documentation.
You can either download the latest release of Winget-Create from its GitHub repository or use Winget to install it for you by running the following command:
winget install wingetcreateNow that you have Winget-Create installed onto your machine, you are ready to generate your first manifest by running the New command. To do so, simply run the following command in your terminal:
wingetcreate new <Installer URL(s)>There are many other commands available in Winget-Create to help you update existing manifests or submit new manifests. Feel free to try it out!
If you decide to create or edit your manifest by manually editing the YAML, it is important to make sure that you are validating your manifest. You can do this by running the validate command from Winget which will tell you if your manifest is valid, or which parts need to be fixed:
winget validate --manifest <Path to manifest>