Add pre-release advice section, and a few small updates.

AUTHORING_MANIFESTS.md

@@ -1,7 +1,7 @@
-[Manifest Specification]:   doc/manifest/schema/1.5.0
-[versionSchema]:            doc/manifest/schema/1.5.0/version.md
-[defaultLocaleSchema]:      doc/manifest/schema/1.5.0/defaultLocale.md
-[installerSchema]:          doc/manifest/schema/1.5.0/installer.md
+[Manifest Specification]:   doc/manifest/schema/1.6.0
+[versionSchema]:            doc/manifest/schema/1.6.0/version.md
+[defaultLocaleSchema]:      doc/manifest/schema/1.6.0/defaultLocale.md
+[installerSchema]:          doc/manifest/schema/1.6.0/installer.md
 
 # Authoring Manifests
 
@@ -40,17 +40,20 @@ You should take a look at our [Manifest Specification]. Don't worry. If this is
 Manifests submitted to the Windows Package Manager Community Repository should be submitted as a multi-file manifest. The minimum required files are a [version][versionSchema] file, a [defaultLocale][defaultLocaleSchema] file and an [installer][installerSchema] file.
 
 ## Creating your first manifest
-Once you have package in mind that doesn't already exist in the repository, you can now start [creating your package manifest](https://docs.microsoft.com/en-us/windows/package-manager/package/manifest?tabs=minschema%2Cversion-example). We recommend using the [Windows Package Manager Manifest Creator (a.k.a Winget-Create)](https://github.com/microsoft/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](Tools/YamlCreate.ps1). More information on using YamlCreate is found in the [script documentation](doc/tools/YamlCreate.md).
+
+Once you have a package in mind that doesn't already exist in the repository, you can now start [creating your package manifest](https://docs.microsoft.com/en-us/windows/package-manager/package/manifest?tabs=minschema%2Cversion-example). We recommend using the [Windows Package Manager Manifest Creator (a.k.a Winget-Create)](https://github.com/microsoft/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](Tools/YamlCreate.ps1). More information on using YamlCreate is found in the [script documentation](doc/tools/YamlCreate.md).
 
 
 ### How do I install Winget-Create?
+
 You can either [download the latest release of Winget-Create](https://github.com/microsoft/winget-create/releases) from its GitHub repository or use **Winget** to install it for you by running the following command:
 
 ```powershell
 winget install wingetcreate
 ```
 
 ### Creating your manifest with Winget-Create
+
 Now that you have Winget-Create installed onto your machine, you are ready to generate your first manifest by running the [New command](https://github.com/microsoft/winget-create/blob/main/doc/new.md). To do so, simply run the following command in your terminal:
 
 ```powershell
@@ -61,13 +64,15 @@ There are many other commands available in Winget-Create to help you [update exi
 
 
 ## Validation
+
 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](https://aka.ms/winget-command-validate) from **Winget** which will tell you if your manifest is valid, or which parts need to be fixed:
 
 ```powershell
 winget validate --manifest <Path to manifest>
 ```
 
 ## Testing
+
 It is important to test your manifest before submission to ensure it meets the repository's quality standards. While it isn't possible to describe everything that we check for when reviewing contributions, testing your manifest helps keep the quality of contributions high and increases the chance of your contribution being accepted.
 
 * Manifests should be tested to ensure applications can install unattended
@@ -77,3 +82,42 @@ It is important to test your manifest before submission to ensure it meets the r
 
 After enabling the setting for local manifests (`winget settings --enable LocalManifestFiles`), manifests can be tested locally with `winget install --manifest <path>`.
 If your system supports Windows Sandbox, you can also use the [SandboxTest.ps1 Script](https://github.com/microsoft/winget-pkgs/blob/master/doc/tools/SandboxTest.md) to test the manifest in the Windows Sandbox. This is the preferred method, as it ensures the package doesn't require any dependencies to install.
+
+## Pre-release, early release, release candidate, and alpha & beta versions. 
+
+Many packages have "pre-release" PackageIdentifiers, to both spread the pre-release client and also keep mainline users on the stable release. There is definite demand for most pre-release software, and creating a pre-release PackageIdentifier is a great way to help satisfy this demand while still meeting the need to deliver a stable product. Also, there is usually a large community pushback when pre-release packages are submitted under a mainline PackageIdentifier. 
+
+Developers are free to version their products as they please. This section is meant to guide manifest submitters in creating manifests to meet both needs. While we try to ensure packages install and upgrade correctly, we don't necessarily know all software and their release mechanisms/cadences. Having an open-source repository allows individuals with much better knowledge of specific software packages to maintain those packages, including splitting pre-release channels from mainline channels when appropriate. 
+
+### How to tell if it's a release candidate?
+
+- Most developers are very clear about pre-release and mainline versions. Ideally, this would be communicated to users through manifests and PackageIdentifiers. 
+- Some developers might add a common term such as "alpha", "beta", or "pre" - or an alphabet letter such as "b", or other indicator to their version numbers.
+- Other developers might add a different development line with a separate repo, different application names and icons, and separate version schema.
+- Not all letters indicate pre-release channels. For example, some developers append "-E" to the version number, to differentiate mainline Electron releases from their other mainline releases. If in doubt, ask the developer. 
+
+### Adding or removing letters from the version can cause matching issues
+
+- As long as a package version sticks to either semantic or string, it's pretty easy to sort. But switching usually causes the order to become confused.
+**This can cause the "upgrade always available" bug.**
+- This is another problem caused by adding pre-release versions into the mainline channel - it frequently disrupts the sort order, especially when the pre-release versions have letters in their version numbers, but the mainline versions do not.
+
+### How to make pre-release versions available
+
+Usually, just appending the appropriate term to the mainline PackageIdentifier is enough. The appropriate term would depend on how the developers refer to their early releases  - such as `.alpha`, `.beta`, `.pre`,  `.rc`, etc. And this new PackageIdentifier would replace the mainline PackageIdentifier in pre-release manifests, manifest names, and manifest paths. 
+
+Some examples: 
+
+- Mainline PackageIdentifier: `Microsoft.Edge`
+- Mainline Repository path: ./manifests/m/Microsoft/Edge
+- Beta PackageIdentifier: `Microsoft.Edge.Beta`
+- Beta Repository path: ./manifests/m/Microsoft/Edge/Beta
+
+- Mainline PackageIdentifier: `Microsoft.OpenSSH`
+- Mainline Repository path: ./manifests/m/Microsoft/OpenSSH
+- Beta PackageIdentifier: `Microsoft.OpenSSH.Beta`
+- Beta Repository path: ./manifests/m/Microsoft/OpenSSH/Beta
+
+Use the version number that the pre-release software adds to Apps and features Settings page, or other locations including the Registry, so that the WinGet package manager can provide updates to the pre-release version.
+
+Note: Pre-release PackageIdentifiers are subordinate to mainline PackageIdentifiers - if the pre-release PackageIdentifier is causing an issue in the mainline, then the mainline should have priority and the pre-release should be modified or removed.