From b34a93fb4b818135e889a7aa86dec9ce57ca2d19 Mon Sep 17 00:00:00 2001 From: Paul Broadwith Date: Fri, 16 Dec 2022 16:56:35 +0000 Subject: [PATCH 1/5] (#119) Update Statiq.Web version As part of the Moderation documentation overhaul, I want to use Mermaid diagrams. The version of Statiq.Web we use does not support this so we need to update. This is the latest version available at the time. --- Docs.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Docs.csproj b/Docs.csproj index 0c1e95e16b..e02178f7a5 100644 --- a/Docs.csproj +++ b/Docs.csproj @@ -35,6 +35,6 @@ - + \ No newline at end of file From dfa7615bd656f657846ba969e06dfab051b57e36 Mon Sep 17 00:00:00 2001 From: Paul Broadwith Date: Fri, 16 Dec 2022 17:56:19 +0000 Subject: [PATCH 2/5] (#119) Remove TOC --- input/en-us/create/create-packages.md | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/input/en-us/create/create-packages.md b/input/en-us/create/create-packages.md index 2ba4e1ee2f..feb4bde654 100644 --- a/input/en-us/create/create-packages.md +++ b/input/en-us/create/create-packages.md @@ -38,25 +38,6 @@ You have a powerful use of Chocolatey, as you are using PowerShell. So you can do just about anything you need. Choco has some very handy [built-in functions](xref:powershell-reference) that you can use, these are sometimes called [helpers](xref:powershell-reference). -## Table of Contents - -1. [Rules](#rules-to-be-observed-before-publishing-packages) -1. [Encoding](#character-encoding) -1. Learning about NuGet (and Chocolatey) Packages in general - [Information](#okay-how-do-i-create-packages) and [Nuspec](#nuspec) -1. [Description/Release Notes Recommendations](#package-description-and-release-notes) -1. [Limit Windows Versions](#install-only-on-some-versions-of-windows) -1. [Install paths](#installation-paths) -1. [Upgrading](#upgrading) and [Uninstalling](#uninstalling) -1. [Naming your package](#naming-your-package) -1. [Versioning](#versioning-recommendations) (and [package fix version notation](#package-fix-version-notation)) -1. [Icons](#package-icon-guidelines) -1. [Exclude executables from shims](#how-do-i-exclude-executables-from-getting-batch-redirects) -1. [Make shim for GUI application](#how-do-i-set-up-batch-redirects-for-applications-that-have-a-gui) -1. [Localization](#internationalization-and-localization-of-packages) -1. [Building](#build-your-package) / [Testing](#testing-your-package) / [Pushing](#push-your-package) -1. [Maintainer magic - automatically updating packaging](xref:automatic-packaging) -1. [Taking over existing package](xref:package-maintainer-handover) - ## Quick Start guide If you think you got what it takes and just want to know the basic steps to get a package out, there is a special [Quick Start Guide](xref:create-packages-quick-start) for you. From 88d963c1ca7302151633afc0d6c6897b8ebcfa90 Mon Sep 17 00:00:00 2001 From: Paul Broadwith Date: Fri, 16 Dec 2022 18:17:26 +0000 Subject: [PATCH 3/5] (#119) Add licenseUrl --- input/en-us/create/create-packages.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/input/en-us/create/create-packages.md b/input/en-us/create/create-packages.md index feb4bde654..3838cbbdf8 100644 --- a/input/en-us/create/create-packages.md +++ b/input/en-us/create/create-packages.md @@ -147,6 +147,21 @@ Logically, the version is based on the lowest compatible version. But if you don **See also:** [NuGet Version Reference](http://docs.nuget.org/docs/reference/versioning) +### Package Metadata in the Nuspec file + +* `` + This is the name of the package itself and must exist to be able to use the `choco pack` command to create a package. This will contain the package name provided to the `choco new` command automatically. An example would be `microsoft-teams.install`See [naming your package](#naming-your-package) for more information and guidance. +* `` + This is the URL that points to the project that the package is installing. This is likely to be software, therefore this URL would point to the project page for the software. Taking `adobereader` as an example, this would be `https://www.adobe.com/acrobat/pdf-reader.html`. +* `` + This is a comma seperated list of package maintainers. Many maintainers prefer to keep previous maintainers here as a thank you for maintaining the package, even though they may no longer appear as maintainers on the package page. An example would be `pauby, dtgm, doc`. +* `` + This contains the software author / vendor. It should not be the same value as the `` field unless the maintainer is also the software author. An example would be `Python Software Foundation`. +* `` + This is the project copyright and should be used appropriately. Look at anything you can find that states the copyright. An example would be `2022 Google Inc.`. +* `` + This is the URL pointing to the license for the project. It should point directly to where the license is stated by the project rather than pointing at a generic defintiion of that license. As an example, if projectX has a GPL v3 license that is stated in their GitHub repository, then the URL will be _that_ location and not the [GPL v3 license definition](https://www.gnu.org/licenses/gpl-3.0.en.html), `https://github.com/projectX/projectX/license.txt`. + ## But for real, how do I create a package? * **Generate new package**: From d3ec0151b0e53e26c53f35948ac86e3a9ef34c4a Mon Sep 17 00:00:00 2001 From: Paul Broadwith Date: Fri, 16 Dec 2022 18:19:06 +0000 Subject: [PATCH 4/5] (#119) Refactor package requirements --- .../community-repository/moderation/index.md | 38 +++++++++++-------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/input/en-us/community-repository/moderation/index.md b/input/en-us/community-repository/moderation/index.md index 45b641d0fa..54fcf44856 100644 --- a/input/en-us/community-repository/moderation/index.md +++ b/input/en-us/community-repository/moderation/index.md @@ -6,41 +6,47 @@ Description: Information about the package moderation used on the Chocolatey Com RedirectFrom: docs/moderation --- -The community feed, which is found at https://community.chocolatey.org/packages, is a moderated feed. That means all new versions of packages are human reviewed prior to approval to check for safety, quality, and correctness. See [What is moderation](xref:faqs#what-is-moderation) for more details. There are also [trusted packages](xref:faqs#what-is-a-trusted-package), which only go through automated moderation review and bypass human review as they are coming from trusted sources and/or the software vendors themselves. +The [Chocolatey Community Repository](https://community.chocolatey.org/packages, is a moderated packages feed. That means all new versions of packages are moderated prior to approval to check for safety, quality, and correctness. -By safety - we check that the package scripts do not do anything devious and that you get the software that the package indicates you are getting. Please note that the underlying software may contain crapware/malware (although it is usually not installed when allowing Chocolatey to install silently). This is not checked for currently, but we have plans for checking this in licensed versions of Chocolatey because a feature doing that is not free for us to provide. +* Safety: we check that the package scripts do not do anything devious and that you get the software that the package indicates you are getting. Please note that the underlying software may contain [crapware](https://www.computerhope.com/jargon/c/crapware.htm) / malware (although it is usually not installed when allowing Chocolatey to install silently). This is not checked for currently, but we have plans for checking this in licensed versions of Chocolatey because a feature doing that is not free for us to provide. +* Quality: we check that the package contains valid metadata and the package scripts use standard format PowerShell that can be easily read and understood. +* Correctness: we check that the package does what is intended, usually to install and uninstall software. + +These checks are performed by automated moderation review systems on all packages, with human moderators performing the additional last pass checks on all packages that have not reached trusted status. [Trusted packages](xref:faqs#what-is-a-trusted-package) only go through automated moderation review and bypass human review as they are coming from trusted sources and / or the software vendors themselves. See [What is moderation](xref:faqs#what-is-moderation) for more details. ## Definitions -* package - The Chocolatey/NuGet package -* software - The underlying software that the package assists in installing -* installer - The native installer, usually packaged as MSI, NSIS, InstallShield, Wise, Squirrel, or some other flavor. -* the validator - The [package validation service](xref:package-validator) checks the quality of a package based on requirements, guidelines and suggestions for creating packages for Chocolatey’s community feed. We like to think of the validator as unit testing. It is validating that everything is as it should be and meets the minimum requirements for a package on the community feed. -* the verifier - The [package verifier service](xref:package-verifier-service) checks the correctness (that the package actually works), that it installs and uninstalls correctly, has the right dependencies to ensure it is installed properly and can be installed silently. The verifier runs against both submitted packages and existing packages (checking every two weeks that a package can still install and sending notice when it fails). We like to think of the verifier as integration testing. It’s testing all the parts and ensuring everything is good. +* `package`: The Chocolatey package +* `software`: The underlying software that the package assists in installing. +* `installer`: The native software installer, usually packaged as MSI, NSIS, InstallShield, Wise, Squirrel, or some other flavor. +* `Package Validator`: The [package validation service](xref:package-validator) checks the quality of a package based on requirements, guidelines and suggestions for creating packages for the Chocolatey Community Repository. We like to think of Package Validator as unit testing for packages. It is validating that everything is as it should be and meets the minimum requirements for a package on the Chocolatey Community Repository. +* `Package Verifier`: The [package verifier service](xref:package-verifier-service) checks the correctness (that the package actually works), that it installs and uninstalls correctly, has the right dependencies to ensure it is installed properly and can be installed silently. The verifier runs against both submitted packages and existing packages (checking every two weeks that a package can still install and sending notice when it fails). We like to think of the verifier as integration testing. It’s testing all the parts and ensuring everything is good. ## Requirements and Guidelines -While probably the most comprehensive, this list may not be fully up-to-date. This should serve as a most general understanding, knowing that the [validator](xref:package-validator) may be checking for newer things than are written here and that reviewers/moderators may find newer things to check from time to time. +These apply to packages submitted to the Chocolatey Community Repository. While probably the most comprehensive, this list may not be fully up-to-date. This should serve as a most general understanding, knowing that the [Package Validator](xref:package-validator) may be checking for newer things than are written here and that reviewers / moderators may find newer things to check from time to time. > :memo: **NOTE** > > Moderators tend to get somewhat picky about properly stating the license, authors (software vendors), and copyright attributions. They are very important to protect both maintainers and the software vendors. -> :memo: **NOTE** -> -> This is still written based on a reviewer reading it, this will get cleaned up more over time to better explain it from a non-reviewer perspective. - ### Existing Packages This section provides the requirements for packages that have had at least one released version approved or exempted. This includes any packages that existed prior to moderation being turned on (possibly an Unknown status). #### Requirements -Requirements represent the minimum quality of a package that is acceptable. When a package version has failed requirements, the package version requires fixing and/or response by the maintainer. Provided a Requirement has flagged correctly, it **must** be fixed before the package version can be approved. The exact same version should be uploaded during moderation review. +Requirements represent the minimum quality of a package that is acceptable. When a package version has failed requirements, the package version requires fixing and / or response by the maintainer. Provided a requirement has flagged correctly, it **must** be fixed before the package version can be approved. The exact same version number should be used when uploading again for moderation review. + +* `` + This is the URL that points to the project that the package is installing. This is likely to be software, therefore this URL would point to the project page for the software. Taking `adobereader` as an example, this would be `https://www.adobe.com/acrobat/pdf-reader.html`. +* `` + This is a comma seperated list of package maintainers. Many maintainers prefer to keep previous maintainers here as a thank you for maintaining the package, even though they may no longer appear as maintainers on the package page. An example would be `pauby, dtgm, doc`. +* `` + This contains the software author / vendor. It should not be the same value as the `` field unless the maintainer is also the software author. An example would be `Python Software Foundation`. +* `` + This is the project copyright and is should be used appropriately. Look at anything you can find that states the copyright. An example would be `2022 Google Inc.`. -* ProjectUrl - it's required for the community feed -* The authors field (software author/vendor) is not being used for the maintainers field (exception: when the maintainer is also the author) -* The copyright is used appropriately. Look at anything you can find that states the copyright. * If there is a license available, it **must** be included in the licenseUrl. * Is the title appropriate? * At least something written in the description. It should be sufficient to explain the software. From 9867eee5d6e3e67443997476d8311b2045b1a88c Mon Sep 17 00:00:00 2001 From: Paul Broadwith Date: Fri, 16 Dec 2022 18:39:39 +0000 Subject: [PATCH 5/5] (#119) Clarify metadata requirements --- .../community-repository/moderation/index.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/input/en-us/community-repository/moderation/index.md b/input/en-us/community-repository/moderation/index.md index 54fcf44856..0b6215e874 100644 --- a/input/en-us/community-repository/moderation/index.md +++ b/input/en-us/community-repository/moderation/index.md @@ -38,17 +38,13 @@ This section provides the requirements for packages that have had at least one r Requirements represent the minimum quality of a package that is acceptable. When a package version has failed requirements, the package version requires fixing and / or response by the maintainer. Provided a requirement has flagged correctly, it **must** be fixed before the package version can be approved. The exact same version number should be used when uploading again for moderation review. -* `` - This is the URL that points to the project that the package is installing. This is likely to be software, therefore this URL would point to the project page for the software. Taking `adobereader` as an example, this would be `https://www.adobe.com/acrobat/pdf-reader.html`. -* `` - This is a comma seperated list of package maintainers. Many maintainers prefer to keep previous maintainers here as a thank you for maintaining the package, even though they may no longer appear as maintainers on the package page. An example would be `pauby, dtgm, doc`. -* `` - This contains the software author / vendor. It should not be the same value as the `` field unless the maintainer is also the software author. An example would be `Python Software Foundation`. -* `` - This is the project copyright and is should be used appropriately. Look at anything you can find that states the copyright. An example would be `2022 Google Inc.`. - -* If there is a license available, it **must** be included in the licenseUrl. -* Is the title appropriate? +##### Package Metadata in the `.nuspec` file + +* The `` field must contain a valid URL to the project. See [package metadata](xref:create-packages#package-metadata-in-the-nuspec-file) for more information on what this field should contain. +* The `` field must not be the same as the `` field, _except_ when the maintainer and the software author are the same. See [package metadata](xref:create-packages#package-metadata-in-the-nuspec-file) for more information on what this field should contain. +* The `` field must contain a valid copyright for the project. See [package metadata](xref:create-packages#package-metadata-in-the-nuspec-file) for more information on what this field should contain. +* The `` field must contain a valid URL that points to th elicense for the project. Note that this should not be a generic license definition but the location of where the license is stated within the project. See [package metadata](xref:create-packages#package-metadata-in-the-nuspec-file) for more information on what this field should contain. + * At least something written in the description. It should be sufficient to explain the software. * The description should explicitly mention if this package installs trial software or software that needs a license present, or both. * The tags field is not being abused - note this doesn't mean they are missing tags you believe they should have (that is a guideline).