Packages Source Files Teamwork Basics - Metadata - AU Script - UI Automation
This repository presents the latest and highest package standards. The purpose of this repository is to provide packages that are:
- Stable - Current and earlier versions should generally work, so you could depend on them. The most stable packages are those that are embedded (see 1.1.4).
- High quality - Packages should be resilient and should provide parameters where adequate.
- Free - Packages should be generally usable by anybody without any special prerequisites.
To achieve those goals we are using the following priorities when adding new or maintaining existing packages:
- Cross-platform FOSS packages.
- Windows only FOSS packages.
- Freeware packages.
- Commercial packages with unrestricted trials.
The following rules also apply:
- When packages have the same priorities, software with higher number of users will generally be considered more important.
- Applications without english localization are not accepted in this repository.
- The core team may decide to stop supporting a package after a discussion. This may happen if the package requires too much dedication during maintenance.
For existing packages that no longer fit above principles chocolatey-community user will be removed from the list of the maintainers.
The following sections present complete set of guidelines, please read them carefully, especially since some rules are enforced and if broken will result in the failed PR build.
Table of Contents
- 1. Packages
- 1.1 Basics
- 1.1.1 Conform to guidelines
- 1.1.2 Manual or automatic
- 1.1.3 Naming
- 1.1.4 Embed a package if allowed
- 1.1.5 Support multiple versions
- 1.1.6 Support multiple architectures
- 1.1.7 Clean code
- 1.1.8 Set
softwareName - 1.1.9 Test locally
- 1.1.10 Dependency versions
- 1.1.11 Provide uninstaller only if needed
- 1.1.12 Ensure compatibility with PowerShell v2+
- 1.1.13 Chocolatey compatibility
- 1.2 Metadata
- 1.3 AU Script
- 1.4 UI Automation
- 1.1 Basics
- 2. Source Files
- 3. Teamwork
Conform with the official package creation guidelines and take a look at quick start guide on how to create packages.
You should also know how to deprecate a package.
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.
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
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 License.txt.
It's 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 explicitly doesn't allow redistribution via adequate license then 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 activepresenter package. Embedding non-allowed binaries may have legal repercussions.
NOTE: 200MB is the maximum size of the package. Larger tools must be downloaded from a vendor site or mirror.
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 versions when users provide the --version parameter to choco install. If this is not possible, add a note that package doesn't support multiple versions.
- If the package doesn't support x64 bit version, do not use
url64bitand related x64 parameters ofInstall-ChocolateyPackage. - If package is only x64, do not use
urland related x32 parameters for future Windows Nano server compatibility. - If the same url is provided for both x64 bit and x32 bit versions, only use the
urland the related parameters. Do not useurl64bitand its related x64 bit parameters.
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).
Chocolatey extension chocolatey-core.extension provides functions that can make the code even more understandable.
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 (it's called Entry Name here).
This information is used for the licensed edition of chocolatey to detect if the software is installed (Business edition) and when the software have been uninstalled (Pro edition).
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.
Although all PRs are tested on appveyor, all packages are expected to have been locally tested before the PR was submitted
- 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 their process or incidentally install some package that uses newer version explicitly set, it will not automatically upgrade to the latest version.
- 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.
- When taking a dependency on anything else, specify minimum or exact version.
Packages should have uninstaller if auto uninstall doesn't work.
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.
For a reference of which cmdlets are available in PowerShell v2, please see the following link: http://adamringenberg.com/powershell2/
Packages are expected to be compatible with the Chocolatey version available 12 months ago. If a later version of Chocolatey is required, then a dependency on the earliest version compatible with the package must be added.
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.
Keep tags lowercase and separate them with spaces. For multi-word tags, use - between words (e.g. cross-platform).
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 proprietary 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.
Description is maintained in the README.md file in the root of the package and automatically set in the nuspec by AU during an update. It 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 |
Keep any existing owners and add chocolatey-community user before all others.
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.
When icon is added to this folder it will automatically be set in the nuspec file and README.md that contains <img> tag.
NOTE: If the packaged software do not provide an icon, add the following to the package metadata file: <!-- IconUrl: Skip check -->.
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).
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 than few MB should never be downloaded within au_GetLatest function. Normally, the files are downloaded during the embedding process by the au_BeforeUpdate.
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:
- If you want to fix the existing CR package version for which no update is available at vendor specify the
NuspecVersionthe same asRemoteVersion. - If you want to push new package version to CR and
RemoteVersiondoesn't exist on CR, setNuspecVersionto0.0. AU updater will then bring the version to correct one during the next AU run and commit it to the git repository. - 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 explicitly 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].
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.
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.
Do not create brittle scripts that work only when user doesn't interfere. 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.
Always use UTF-8 without BOM for the *.nuspec and UTF-8 with BOM for the *.ps1 files. See character encodings.
Do not commit code with obvious styling problems such as irregular indentation levels, very long lines, too many comments, too many empty lines, etc.
The project contains .editorconfig file that can be used with many editors via EditorConfig plugins.
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.
Good communication is essential so please take a look at Code of Conduct regarding it.
If you are submitting or making changes to a package and want to ensure that you can review any further changes, add your name to the CODEOWNERS file.
All contributors should issue pull request containing single package. In special cases multiple packages per PR can be allowed.
Issues that remain open for 2 months without any activity will be marked as pending closure, if addition 14 days goes by without any activity the issue will be closed with the label Unresolved.
Pull Requests that have changes requested, and/or is marked with the label 0 - Waiting on User will be closed after 30 days of inactivity.
Most of the labels are self describing, here are few that require explanation:
- 5 - Push required Package is done when it's pushed to community repository - If you fix the package source code and commit PR, the job is generally not over if it's 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 benefit.
- Unresolved The issue is unresolved - no feedback, no interest, and it probably expired.
- 0 - _Triaging Team is checking, confirming and measuring out the request.
- Pending closure The issue is approaching end of issue lifetime. This is an announcement that the issue will soon get closed in a few weeks, unless there is some new activity.
- 0 - Waiting on user The team is waiting for somebody to respond. Until that happens, there will be no activity.