Naming, Description, and Versioning Recommendations

Naming Your Package

The title of your package (<title> tag in the nuspec) should be the same as the name of the application. Follow the official spelling, use upper and lower case and don't forget the spaces. Examples of correct package titles are: Google  Chrome, CCleaner, PuTTY and FileZilla. The title will appear on the left side in the package list of the Chocolatey gallery, followed by the version.

There are some guidelines in terms of the package id (<id> tag in the nuspec):

• Use only lowercase letters, even if you used uppercase letters in the package title. (This is considered a guideline because it is correctable in other ways). Once a package is submitted (even prior moderation), the Gallery will always show the id with the casing of the first package version. In addition, changing the casing of the package id may have negative side effects on dependencies (note: this last statement needs verified).
• If the original application name consists of compound words without spaces (CamelCase), just as MKVToolNix, TightVNC and VirtualBox, the package id's are simply the same (but lowercase of course): mkvtoolnix, tightvnc, and virtualbox.
• If the name of the application contains multiple words separated by spaces, such as MusicBrainz  Picard or Adobe Reader, replace the spaces with the hyphen-minus character " - " (U+002D) or just omit them. Don't use dots. They should be used only if the original application name contains dots (e.  g. Paint.NET). Hence the correct id's of the previously mentioned applications can be musicbrainz-picard or adobereader. It is highly suggested to use the hyphen method when there are long package names, because that increases readability.
• For sub-packages, use the hyphen-minus character " - " (U+002D) as separator, not a dot. Sub-packages are intended for separate packages that include extensions, modules or additional features/files for other applications. Therefore keepass-langfiles is a proper package id, because it adds the language files for the main application which in this case is KeePass. Another example is libreoffice-help for the help pack for LibreOffice, the open source office suite.
• If you want to package an open source application, look on the repositories of some popular Linux distributions, such as Debian, Ubuntu and Arch Linux if they already have a package of it. If that is the case, use the same package id. This will make it easier for Linux and Windows users, because then they don't have to remember and use different package names.

These guidelines are already commonly applied on packages for all major Linux distributions, because they lead to a more consistent look of software repositories, easier to remember package id's and less considerations about the naming for package creators.

Note that a lot of packages in the Chocolatey Gallery don't follow these guidelines. The simple reason is that the affected packages were created before the introduction of these guidelines.

If you are going to offer a package that has both an installer and an archive (zip or executable only) version of the application, create three packages   - see Portable vs Installable and Install, Portable, and Meta/Virtual Packages

Description and Release Notes

The <description> of the package should contain a short text or at least a few words about the software for which the package is made. Here are a few things that should be respected:

• The description should always be written in English, even if the packaged software does not provide an UI in English. You can also include the software's description in its original language, but insert it after the English description.
• The description should not just contain a repetition of the package name.
• It should not just consist of a link where more information can be found. For that purpose there's already <projectUrl>.
• The contents of <description> and also <releaseNotes> are parsed as Markdown, so don't insert line breaks in the middle of sentences. Remember to add empty lines to separate paragraphs and add an empty line before a list.

Versioning Recommendations

Versioning can be both simple and complicated. The best recommendation is to use the same versioning that the installable/portable application uses. With Chocolatey you get four version segments. If the application only uses 1, 2 or 3 version segments, follow suit.

If the 4th segment is used, some folks like to drop the segment altogether and use that as only the package fix notation using one of the notations in the next section. There is no recommendations at this time.

The main release of a product versions are usually sufficient. If there are also beta versions available and you would rather have that, then please create both the official release and the beta (and set the beta as a prerelease when pushing the item to chocolatey.org). Regular users of packages may want to use official releases only and not betas.

Package Fix Version Notation

Package fix version notation ONLY applies when you are making a fix to the package because the existing version of a package is incorrect in some way. So if the software is 1.1.0, in a normal scenario the package version should be 1.1.0. If you find that the 1.1.0 package has an issue and you need to fix the package but keep the same version of the software, that is where package fix version notation comes into play. You would end up with both a 1.1.0 package and a 1.1.0.YYYYMMDD version of the package.

If you need to fix an approved package for some reason, you can use the fourth version element (aka segment) for a package fix notation. There are two recommended methods of package fix version notation:

• Date (Year/Month/Day) - Some folks use year month day package fix notation (yyyyMMdd as in 20120627 seen as 1.2.0.20120627)
• Sequential - Not recommended - Some folks use sequential numbering (0, then 1, etc as in 0 for no fix, 1 for first fix and so on seen as 1.2.0.0 and 1.2.0.1).

Date Package Fix Version Notation is recommended because one can ascertain what it is immediately upon seeing it, where sequential is not obvious on sight whether it is part of the software versioning or something special with the package.

Package fix version notation is only acceptable in the fourth segment. Do not use any of the other segments for package fix notation. If an application only uses 1 or 2 version segments, add zeros into the other segments until you get to the 4th segment (i.e.  1.0.0.20120627).

When the fourth segment is already used, it is recommended to add two zeroes (00) to the end of the version. Then when you need to fix, you just increment that number. So if the package was ruby and the version was 2.0.0-p353, the package is 2.0.0.35300 (adding the two zeroes at the end). Then a fix would be 2.0.0.35301 and so on. WARNING: If you decide to add a secondary set of numbers to the fourth segment, you MUST ALWAYS include that secondary set of numbers while the other three version segments are the same. The reason - if you fix .1 to .100, then release .2, .100 is greater than .2 because versioning doesn't look at the " . ", only the number in the element. So 100 is greater than 2.

Internationalization and localization of packages

For Chocolatey, internationalization and localization of packages is very important, because it has users from all over the world. Many applications support multiple languages, but they use several different methods to achieve that. Therefore, there is no standard how internationalization/localization has to be integrated into packages. However, here are a few examples of packages that use various techniques. You can use them as inspiration for new packages:

• The ideal situation is when an application determines the user's system language and automatically installs with that language. Then you don't have to take any action relating to localization, because the application already handles that. Examples of such applications are VLC Media Player and LibreOffice.
• When an application provides different installers for different languages, you should determine the system language and download the appropriate installer. The package for Mozilla Firefox (source code) uses this method.
• Sometimes an application installer or executable has already integrated all supported languages, but doesn't automatically select the system language during a silent install. Often you can pass an additional install parameter to select the desired language. This is used for example in the CCleaner package (source code).
• Some application use separate language files which must be downloaded separately and put somewhere in the application directory. It is best when you create a separate package for the language files. If your package id is packageid, then call it packageid-langfiles. The language files package for KeePass is an example how this can be achieved.

Additional Tips

Dependecy Chaining

You can make packages that depend on other packages just by adding those dependencies to the nuspec. Take a look at ferventcoder.chocolatey.utilities nuspec.

Avoid Folders Named "Content"

Do not use a folder named "content" in your package. NuGet attaches a special meaning to this folder and will not allow you to have dependencies on packages that have content folders without also having a content folder. It's turtles all the way down until we or NuGet removes this limitation.