(#119) Overhaul package moderation docs #624
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
|
|
||
| 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. |
There was a problem hiding this comment.
Probably would be good to add in a note about scanning here, because malware is checked for with the scanner.
| * `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. |
There was a problem hiding this comment.
And add a section about the scanner here as well.
|
|
||
| * 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. |
There was a problem hiding this comment.
Probably should add a note about the description minimum length, or reword this.
gep13
requested changes
Dec 19, 2022
| ### Package Metadata in the Nuspec file | ||
|
|
||
| * `<id>` | ||
| 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 `<id>microsoft-teams.install</id>`See [naming your package](#naming-your-package) for more information and guidance. |
There was a problem hiding this comment.
Suggested change
| 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 `<id>microsoft-teams.install</id>`See [naming your package](#naming-your-package) for more information and guidance. | |
| 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 `<id>microsoft-teams.install</id>`. See [naming your package](#naming-your-package) for more information and guidance. |
| * The `<projectUrl>` 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 `<authors>` field must not be the same as the `<owners>` 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 `<copyright>` 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 `<licenseUrl>` 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. |
There was a problem hiding this comment.
Suggested change
| * The `<licenseUrl>` 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. | |
| * The `<licenseUrl>` field must contain a valid URL that points to the license 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. |
| @@ -166,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 | |||
There was a problem hiding this comment.
Should this part be made into a fragment, as similar information is provided earlier in this PR.
|
@pauby are you planning on taking another go at this, or is the issue available for someone else to be assigned to it? |
7 tasks
|
@TheCakeIsNaOH was an overzealous branch cleanup. I've raised #1002 to cover it.
You are welcome, as is anybody else, to contribute to this. Just a heads-up though, my goal is to completely rewrite the moderation docs rather than updating them. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description Of Changes
Overhauling the package moderation docs to make them easier to follow for both moderators and maintainers going through the process.
Motivation and Context
Many reasons. #119 has the best explanation.
Testing
Change Types Made
Change Checklist
Related Issue
#119