Skip to content

Commit

Permalink
Update command docs and fix typo in a resource string (microsoft#546)
Browse files Browse the repository at this point in the history
  • Loading branch information
mdanish-kh authored Sep 5, 2024
1 parent 978b0a7 commit d758023
Show file tree
Hide file tree
Showing 4 changed files with 44 additions and 12 deletions.
16 changes: 16 additions & 0 deletions doc/new.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,29 @@ By typing **ENTER** you will accept the string, and the wizard will move on.

![new command PackageIdentifier](./images/create-packageidentifier.png)

### Auto-filling manifest fields

If the installer URLs come from a GitHub release, the CLI can automatically fill in missing manifest metadata. A valid GitHub token must be provided using the `--token` argument to use this feature.
The new command flow may automatically fill in the following fields:

- `License` - The license from the GitHub repository.
- `ShortDescription` - The description from the GitHub repository.
- `ReleaseDate` - The publish date of the release on GitHub.
- `ReleaseNotesUrl` - The URL to the release notes on GitHub.
- `PackageUrl` - The URL to the package GitHub repository.
- `PublisherUrl` - The URL to the publisher's GitHub page.
- `PublisherSupportUrl` - The URL to GitHub issues for the package repository.
- `Tags` - The tags from the GitHub repository.
- `Documentations` - If the GitHub repository has a wiki, the URL to the wiki will be added to the manifest.

### Remaining required fields

Like the **PackageIdentifier** you will have the opportunity to accept or modify the remaining fields.

![new command default values](./images/create-defaults.png)

### Review Changes

Once you have successfully filled in the details, fields, **Winget-Create** will display the results for you to review.

![new command review](./images/create-review.png)
Expand Down
36 changes: 26 additions & 10 deletions doc/update.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The **update** command of the [Winget-Create](../README.md) tool is designed to

## Usage

`wingetcreate.exe update <id> [-u <urls>] [-v <version>] [-s] [-t <token>] [-o <output directory>] [-p <pull request title>] [-r] [<replace version>]`
`wingetcreate.exe update <id> [-u <urls>] [-v <version>] [-s] [-t <token>] [-o <output directory>] [-p <pull request title>] [-r] [<replace version>] [-d <display version>] [--release-date <release date> ] [--release-notes-url <release notes url>] [--format <format>] [--interactive] [--help]`

The **update** command can be called with the installer URL(s) that you wish to update the manifest with. **Please make sure that the number of installer URL(s) included matches the number of existing installer nodes in the manifest you are updating. Otherwise, the command will fail.** This is to ensure that we can deterministically update each installer node with the correct matching installer url provided.

Expand Down Expand Up @@ -34,6 +34,19 @@ e.g.,

`wingetcreate update <PackageIdentifier> --urls '<InstallerUrl1>|x64|user' '<InstallerUrl1>|x64|machine' '<InstallerUrl2>|x86|user' '<InstallerUrl2>|x86|machine'`

### Auto-filling manifest fields

If the installer URLs come from a GitHub release, the CLI can automatically fill in missing manifest metadata. A valid GitHub token must be provided using the `--token` argument to use this feature.
The update flow may automatically fill in the following fields:

- `ReleaseDate` - The publish date of the release on GitHub.
- `ReleaseNotesUrl` - The URL to the release notes on GitHub.
- `PackageUrl` - The URL to the package GitHub repository.
- `PublisherUrl` - The URL to the publisher's GitHub page.
- `PublisherSupportUrl` - The URL to GitHub issues for the package repository.
- `Tags` - The tags from the GitHub repository.
- `Documentations` - If the GitHub repository has a wiki, the URL to the wiki will be added to the manifest.

### Installer URL arguments

The following additional arguments can be provided with the installer URL(s):
Expand Down Expand Up @@ -94,16 +107,19 @@ The following arguments are available:

| Argument | Description |
|--------------|-------------|
| **id** | Required. Package identifier used to lookup the existing manifest on the Windows Package Manager repo.
| **-u, --urls** | Installer Url(s) used to extract relevant metadata for generating a manifest
| **-v, --version** | Version to be used when updating the package version field.
| **-i, --interactive** | Boolean value for making the update command interactive. If true, the tool will prompt the user for input. Default is false.
| **-o, --out** | The output directory where the newly created manifests will be saved locally
| **-s, --submit** | Boolean value for submitting to the Windows Package Manager repo. If true, updated manifest will be submitted directly using the provided GitHub Token
| **-r, --replace** | Boolean value for replacing an existing manifest from the Windows Package Manager repo. Optionally provide a version or else the latest version will be replaced. Default is false.
| **-p, --prtitle** | The title of the pull request submitted to GitHub.
| **id** | Required. Package identifier used to lookup the existing manifest on the Windows Package Manager repo. |
| **-u, --urls** | Installer Url(s) used to extract relevant metadata for generating a manifest |
| **-v, --version** | Version to be used when updating the package version field. |
| **-d, --display-version** | Version to be used when updating the display version field. Version provided in the installer URL arguments will take precedence over this value. |
| **--release-notes-url** | URL to be used when updating the release notes url field. |
| **--release-date** | Date to be used when updating the release date field. Expected format is "YYYY-MM-DD". |
| **-o, --out** | The output directory where the newly created manifests will be saved locally |
| **-p, --prtitle** | The title of the pull request submitted to GitHub. |
| **-s, --submit** | Boolean value for submitting to the Windows Package Manager repo. If true, updated manifest will be submitted directly using the provided GitHub Token |
| **-r, --replace** | Boolean value for replacing an existing manifest from the Windows Package Manager repo. Optionally provide a version or else the latest version will be replaced. Default is false. |
| **-i, --interactive** | Boolean value for making the update command interactive. If true, the tool will prompt the user for input. Default is false. |
| **-f,--format** | Output format of the manifest. Default is "yaml". |
| **-t, --token** | GitHub personal access token used for direct submission to the Windows Package Manager repo. If no token is provided, tool will prompt for GitHub login credentials.
| **-t, --token** | GitHub personal access token used for direct submission to the Windows Package Manager repo. If no token is provided, tool will prompt for GitHub login credentials. |
| **-?, --help** | Gets additional help on this command. |

## Submit
Expand Down
2 changes: 1 addition & 1 deletion src/WingetCreateCLI/Properties/Resources.Designer.cs

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion src/WingetCreateCLI/Properties/Resources.resx
Original file line number Diff line number Diff line change
Expand Up @@ -1364,7 +1364,7 @@
<value>Base manifest contains DisplayVersion that has not been updated. Use --display-version CLI arg or provide the version in the installer URL.</value>
</data>
<data name="DisplayVersion_HelpText" xml:space="preserve">
<value>Version to be used when updating the display version field. Version provided in the installer URL arguments will take precendence over this value.</value>
<value>Version to be used when updating the display version field. Version provided in the installer URL arguments will take precedence over this value.</value>
</data>
<data name="UsingDisplayVersion_Message" xml:space="preserve">
<value>Using display version '{0}' for {1}</value>
Expand Down

0 comments on commit d758023

Please sign in to comment.