Course Summary, Rules, and Guidlines

Course Summary

First you should determine if you are making a self-contained package or (also) using automation scripts. You should also consider creating automatic packages for the best maintainability over time.

1. Run choco new -h to get a feel for what you can pass e.g choco new bob (to create a package named bob)
2. Note all the rules below. This will help you, especially in publishing to the community feed (https://community.chocolatey.org)

Self-Contained?

If you have a self-contained package, you can remove the automation scripts entirely and just include the runtime executables, they will automatically get shimmed, which puts them on the path. Ensure you have the legal right to distribute the application though. You should read up on the Shim Generation section below though to familiarize yourself on what to do with GUI applications and/or ignoring shims (also known as batch redirects).

Including the Software Installer in the Package

Sometimes called embedding the binaries, there are functions in the automation scripts you can call that will use the installers directly from the package instead of downloading first. This makes for the most reliable and deterministic packages, but ensure you have the legal right to distribute the software first if publishing to a public location (like the community package repository).

Automation Scripts

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 that you can use, these are sometimes called
helpers.

Rules to be Observed Before Publishing Packages

There are a few rules that you have to follow before pushing packages to chocolatey.org:

1. Don't package illegal software. Packages of software that is illegal in most countries in the world are prohibited to publish on Chocolatey.org. This applies in particular to software that violates the copyright, pirated software and activation cracks. Remember that this also affects software that is especially designed to accomplish software piracy.
2. Do not include software in a package that you don't have the right to distribute. Please see Distribution Rights for more information. Any package found not in compliance with this will be removed immediately. Instead you can download binaries from official distribution locations at runtime.
3. Packaging commercial or trial software? Clearly state this in the package description. Does it require an activation key? Is there a trial period if you don't have a key? How long is this trial period?
4. Only post publicly relevant packages. You should consider whether this package is useful for others. If that is not the case, it shouldn't be published on Chocolatey.org. Reasons for that can be if the package would require a very customized configuration. You can host your personal packages on MyGet and still be able to install them with Chocolatey using the -source parameter.
5. Do not publish junk or malware packages.
6. Don't package software containing malware. Packages of software that comes with bundled adware, spyware or other unrelated software that installs even in silent mode, are not allowed. But if you can figure out how to install the desired software without this unrelated software, it is allowed to publish the package. That can be accomplished for example with additional command line switches or by adding specific values to the registry. Examples of packages which make use of this are PDFCreator and CCleaner.
7. Don't package software that is already packaged. Use the search function in the Chocolatey.org gallery and look if there is already a package for the desired software. If you would like to improve the already existing package or if you have suggestions, just contact the package maintainer or open a pull request at the maintainer's package repository.
8. Don't include other required software if there's a package of it. If a package requires other software of which there is already a package, the already existing package should be used as dependency instead.
9. Split dependencies into multiple packages. Try to split up packages as much as possible. If for example a program comes with additional modules/installers that are optional, make different packages for them instead of including all the things into one package. This idea is already widely applied for Linux packages, because it leads to a more lightweight system and reduces potential issues and conflicts.
10. Use a simple intuitive lowercase name for the package. See the package naming guidelines for details. (If you are a reviewer/moderator, this is considered a guideline).

Is your package unqualified for the Chocolatey feed, but you like to be able to install it through Chocolatey? Don't worry, you can always host your package for free on MyGet. See Hosting Chocolatey Packages on MyGet.

Character Encoding

• Use the UTF–8 character encoding for the *.nuspec and *.ps1 files. If you don't respect this rule, some characters are not displayed correctly in the Gallery on Chocolatey.org, because the Gallery assumes UTF-8.
• Do not save your *.nuspec files with a Byte Order Mark (BOM). A BOM is neither required nor recommended for UTF-8, because it can lead to several issues.
• PowerShell scripts need to be saved in UTF–8 with BOM. PowerShell is ignoring the standards and needs a BOM in order to recognize scripts as UTF-8. Otherwise it processes non ASCII characters incorrectly.
• Don't use the default Windows Editor. In addition to its lack of features, it can't even save UTF-8 files without BOM.
  Alternatives:
  • Visual Studio Code
  • Notepad++
  • Geany
• Use this XML declaration: <?xml version="1.0" encoding="utf-8"?>.

Package Icon Guidlines

If there is an icon which is suitable for your package, you can specify it in the <iconUrl> tag in the nuspec. But there are a few things you should consider:

• Avoid hotlinking icons from sites where you don't have control over the file. If you have a packages repository (recommended), use your own copy of the icon and put it there.
• Use a static CDN for icon URLs that permits you to serve files hosted in a repository on GitHub. Some CDN services cache files permanently and it's therefore best to use a specific tag or commit URL, not a branch URL. While we don't make any recommendations about specific services, the more popular ones used by maintainers are jsDelivr, Staticaly and Githack.
• Avoid using GitHub raw links (https://raw.githubusercontent.com/...). They are not intended to be used as CDN.
• Use the software's icon if one is available, not the logo. This blog post explains the difference between logos and icons: http://blog.designcrowd.com/article/353/differences-between-logos-and-icons. If the software of your package doesn't have an icon, but a logo with text and an image, you can extract the image with your favorite image editor and use that as package icon. An example is MySQL's dolphin.
• Use package icons with at least 128 pixels in width or height if available. However, avoid very high resolutions, because this would only unnecessarily increase the page load time. If there are only icons with less than 128 pixels available, choose the icon with the highest resolution you can find without upscaling it. Don't use low resolution favicons as package icons.
• Use icons with transparent background if available.
• Don't use distorted or blurry icons.
• The package list in the gallery shows the icons with a maximum of 48 pixels in width/height. Application logos with very detailed graphics that are barely visible at that dimension are not suitable as package icons.
• PNG is the preferred format for raster package icons. Avoid ICO, GIF and JPEG graphics.
• Good sources for package icons are the official desktop icons of the corresponding application you want to make a package of. The icons can be extracted from the app executables using tools like BeCyIconGrabber. Remember to take the icon with 128 pixels or more and save it as PNG file.

The icon shown on the Chocolatey.org package page is saved, and served, locally to mitigate against cross scripting attacks and to prevent getting non HTTPS assets errors on the website. Sometimes the page loads faster than the image can be served and the default image gets cached and as a result the new package icon may not be shown until you clear the browser cache for Chocolatey.org and wait 3 hours before reloading the page.