Contributing guidelines

Kim Nordmo edited this page Feb 9, 2017 · 103 revisions

This repository presents the latest and highest package standards. Please read the following sections carefully.

All contributors should issue pull request containing single package. In special cases multiple packages per PR can be allowed.


    Packages                                                                                 Source Files    Teamwork
    Basics - Metadata - AU Script - UI Automation - Icons


1. Packages

1.1 Basics

1.1.1 Conform to guidelines

Conform with the official package creation guidelines and take a look at quick start guide on how to create packages.

You shoould also know how to deprecate a package.

1.1.2 Manual or automatic

Decide if package is manual or automatic. Generally, packages without vendor updates for minimum 3 years should be considered manual. Automatic packages must use AU module.

1.1.3 Naming

Both package root directory and nuspec file should be named the same as the package Id with all lower letters. This is only relevant for new packages, as changing casing on existing packages may have negative side effects

1.1.4 Embed a package if allowed

Embedded packages include the packaged software directly in the nupkg archive instead of downloading it. Only tools that allow redistribution in their license can be embedded and such packages must include two additional files in the directory legal - VERIFICATION.txt and file with information about the license.

Its recommended to create embedded packages because they don't depend on vendor site working and substantially reduce the network related problems - 404 (file not found) problem and potential vendor bandwidth leaching issues are completely solved by embedding.

Binary files can not be generally checked in into this repository because that will bloat it too much. The repository is ignoring binary files via .gitignore. Automatic packages use AU functions to produce correct package that includes binaries during automatic update procedure. See the following packages as an example: qbittorent, less, smplayer.

For software that explicitelly doesn't allow redistribution via adequate license the one may contact the vendor, ask for the redistribution rights and provide proof in the package in the form of:

  • PDF of a signed license
  • signed letter
  • PDF of an email chain granting that permission

As an example take a look at the balsamiqmockups3 package. Embeding non allowed binaries may have legal repercussions.

NOTE: 150MB is the maximum size of the package. Larger tools must be downloaded from a vendor site or mirror.

1.1.5 Provide icon

Packages must have an icon if one is available. The icon must be named the same as the package and is placed in the icons directory.

If the package name ends with either .install or .portable those suffixes may be ignored in the icon name.

1.1.6 Support multiple versions

Packages should support multiple versions if possible - do not use URLs that are not version specific with non-embedded packages as they will install wrong version when user provides --version parameter to choco install. If this is not possible, add a note that package doesn't support multiple versions.

1.1.7 Support multiple architectures

  • If the package doesn't support x64 bit version, do not use url64bit and related x64 parameters of Install-ChocolateyPackage.
  • if package is only x64, do not use url and related x32 parameters for future Windows Nano server compatibility.

1.1.8 Clean code

Remember, code is written for humans, not for computers. Otherwise we'd all write assembly. So it's better to be able to reason about code than it is to take shortcuts that make code harder to decipher.

If you created custom helper functions put them all in the helpers.ps1 to keep installer clean and understandable (example).

Use Aliases sparingly. Aliases are great for scripting or interactive use, but not for production code. They tend to make PowerShell harder to read, sometimes they are not available in all supported versions of PowerShell (Chocolatey supports PowerShell v2+), and someone can override aliases locally (explicitly or implicitly depending on what PowerShell modules are installed), which produces extremely hard to debug issues.

Chocolatey extension chocolatey-core.extension provides functions that can make the code even more understandable.

1.1.9 Set softwareName

If the package uses Install-ChocolateyPackage softwareName should be set to represent software Display Name correctly. You can use myuninstaller package to quickly determine it.

This information will be used in the future to detect if software is already installed and for better synchronization of chocolatey with Programs and Features installations that were done outside of the chocolatey.

1.1.10 Test locally

Before pull request make sure package can install and uninstall correctly using the chocolatey test environment. It is used as a reference machine to prevent it works on my computer syndrome. AU function Test-Package -Vagrant can speed this up.

1.1.11 Dependency versions

  1. When taking a dependency on an extension, specify the minimum version. Without this, any version satisfies the dependency. That means unless someone upgrades the extension outside of their process or incidentally install some package that uses newer version explicitly set, it will not automatically upgrade to the latest version.
  2. When creating a dependency for virtual package, use exact version of the dependent package (.install or .portable) which should be the same as that of virtual package.
  3. When taking a dependency on anything else, specify minimum or exact version.

1.1.12 Provide uninstaller only if needed

Packages should have uninstaller if auto uninstall doesn't work.

1.1.13 Ensure compatibility with PowerShell v2+

Chocolatey supports PowerShell v2+ because it supports Windows 7+/Windows Server 2008+ (Windows Server 2003 is supported currently, but is deprecated and expected to be removed in a future version). Due to that, PowerShell v2 is expected to work when you run anything here.

1.2 Metadata

1.2.1 Obligatory metadata

Make sure the following metadata is present and correct (unless it doesn't apply): packageSourceUrl, projectSourceUrl, docsUrl, bugTrackerUrl, releaseNotes, licenseUrl, iconUrl.

packageSourceUrl must not point to the repository root but to the package root directory.

1.2.2 Obligatory tags

Keep tags lowercase. Use - between words. The following tags are mandatory to use if they apply:

tag meaning
foss for all free and open source packages
cross-platform for all packages available on other platforms then Windows
freeware for all freeware but not open source packages
trial for all propriatery commercial tools that require license
cli for all command line tools
games for all games

Note: If the software provides both free and paid variant within the same executable so that free version doesn't have a time limit, mark them as both freeware and trial.

1.2.3 Informative description

description should include the following 2nd level headers (##) in the given order:

header meaning
Features Bullet list with basic software functionality
Package parameters Bullet list with of all package parameters
Notes Bullet list with any special information to the user if any

1.2.4 Add chocolatey among owners

Keep any exisiting owners and add chocolatey user before all others.

1.3 AU Script

1.3.1 Use UseBasicParsing [Optional]

If you use Invoke-WebRequest to download a web page, try to use UseBasicParsing if possible. Otherwise, the script will require IE engine installed on Windows Server used to run the updater and may also break due to the accept cookie popup (see #382).

1.3.2 Do not download large files

Unless the package installer/executable/archive needs some special handling (like the need to read version from file, or something else not available to be handled by AU), anything bigger then few MB should never be downloaded within au_* functions.

1.3.3 Specify correct NuspecVersion

Since commit message is used to push packages to the community repository (CR), prior to commit of the AU package specify correct NuspecVersion in the nuspec file as follows:

  1. If you want to fix the exisiting CR package version for which no update is available at vendor specify the NuspecVersion the same as RemoteVersion.
  2. If you want to push new package version to CR and RemoteVersion doesn't exist on CR, set NuspecVersion to 0.0. AU updater will then bring the version to correct one during the next AU run and commit it to the git repository.
  3. If you want to fix package that is pushed but not yet approved (for example it fails verifier) do the same as in first case but request in PR comment that you want version explicitelly set.

NOTE: Automatic fix version doesn't work if package is using the revision part of the version (4th number). In that case explicit version must be used: [AU package:version].

1.4 UI Automation

Some installers do not provide silent arguments and can be difficult to automate.

If the package needs to perform tasks that cannot be done with command line switches, e.g. clicking away a prompt during installation that cannot be suppressed like for example in the dropbox package, you can use AutoHotkey. Make autohotkey.portable a dependency of the package. Prefer AutoHotkey over AutoIt, because AutoHotkey is more lightweight, FOS and more actively developed than AutoIt.

1.4.1 Work on all locales

Script must work on every locale available for Windows, so be careful when using strings of text of window in the script that could be different in another language.

1.4.2 Avoid brittle scripts

Do not create brittle scripts that work only when user doesn't interfer. All script elements should be as precise as possible - for instance, instead of using Send function which will work correctly only if the desired window is active, use ControlSend which doesn't require window activation or use BlockInput for short period of time.

1.5 Icons

1.5.1 Follow the guidelines

Follow the package icon guidelines.

1.5.2 Use commit hash

Use

https://cdn.rawgit.com/chocolatey/chocolatey-coreteampackages/{{commitHash}}/icons/{{packageID}}.{{fileExtension}}

as iconUrl. Replace {{commitHash}} with the actual hash of the commit where you added the icon. This makes necessary that adding packages to the repository consists of at least two commits - one for adding the icon, and another for the iconUrl using the previous commit hash as part of the iconUrl.

Updating icons also requires to update the commit hash in the iconUrl, otherwise it will still point to the older version of the icon.

  • NOTE: You can read more about how to get the commit hash, or automate the adding of an icon Url on "How to add Icon Url"

2. Source Files

2.1 Encoding

Always use UTF-8 without BOM for the *.nuspec and UTF-8 with BOM for the *.ps1 files. See character encodings.

2.2 Formatting

  • Indentation: 2 spaces.
  • Replace tabs with spaces.
  • Limit script files to 150 characters per line (except lines with URLs).
  • No trailing spaces
  • Empty line at the end of each file

Consider installing the EditorConfig plugin for your favorite editor.

2.3 Comments

Keep the package source files clean and remove obsolete or outdated code and unnecessary comments. Comment non-obvious code so that others can easily understand what it does.

3. Teamwork

Good communiction is essential so please take a look at etiquette regarding it.

3.1 Push request expires after 6 months

PRs that remain open for 6 months without any feedback may be closed with label Unresolved.

3.2 Open issue expires after 6 months

Issues that remain open for 6 months without any feedback may be closed with label Unresolved.

3.3 Pull request one package

Do not mix multiple packages in single pull request unless in specific special cases that fix common problem.

3.4 Understanding labels

Most of the labels are self describing, here are few that require explanation:

  • Push required
    Package is done when its pushed to community repository - If you fix the package source code and commit PR, the job is generally not over if its not pushed. Using AU package can be pushed with commit commands but sometimes its overseen.
  • Wontfix
    Team doesn't think there is anything to fix here or that time required to fix it doesn't justify the benfit.
  • Unresolved
    The issue is unresolved - no feedback, no interest and it probably expired.
  • Triaging
    Team is checking, confirming and measuring out the request.
  • Pending closure
    The issue is approaching end of issue life time. This is annoucement that issue will soon get closed in few weeks unless there is some new activity.