From 3c3ca8d53085935fcc2670d61f2119b410360cf7 Mon Sep 17 00:00:00 2001 From: "Kim J. Nordmo" Date: Mon, 27 Jun 2022 10:35:29 +0200 Subject: [PATCH] (#1754) Update documentation about contributing to repo This commit updates the documentation we have for contributing to the repository that needs to be followed. --- .github/workflows/toc.yml | 2 +- COMMITTERS.md | 52 +++++ CONTRIBUTING.md | 476 +++++++++++++++++++++++--------------- 3 files changed, 347 insertions(+), 183 deletions(-) create mode 100644 COMMITTERS.md diff --git a/.github/workflows/toc.yml b/.github/workflows/toc.yml index 377d9d2e860..2414d602b4a 100644 --- a/.github/workflows/toc.yml +++ b/.github/workflows/toc.yml @@ -15,7 +15,7 @@ jobs: with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} CREATE_PR: true - TARGET_PATHS: "README*.md,CONTRIBUTING*.md" + TARGET_PATHS: "README*.md,CONTRIBUTING*.md,COMMITTERS*.md" FOLDING: true COMMIT_MESSAGE: '(docs) Update TOC' PR_TITLE: '(docs) Update TOC (${PR_MERGE_REF})' diff --git a/COMMITTERS.md b/COMMITTERS.md new file mode 100644 index 00000000000..45b6042ee20 --- /dev/null +++ b/COMMITTERS.md @@ -0,0 +1,52 @@ +# Committers Guidelines + +This file details what is needed for different operations in the repository that can not be handled by opening pull requests. + + + + +
+Table of Contents + +- [Providing fixed version](#providing-fix-version) + - [Request a standard fix version creation](#request-a-normal-fix-version-creation) + - [Request a standard fix version creation for a stream](#request-a-normal-fix-version-creation-for-a-stream) + - [Request a fixed version update](#request-a-fixed-version-update) + - [Requesting a fix for a package using 4-part version number](#requesting-a-fix-for-a-package-using-4-part-version-number) + +
+ + + + +## Providing A Fixed Version + +Before providing a fixed package version, you need to determine the existing version specified in the repository, what type of version it uses, and whether the package contains additional handling for creating fixed versions. + +### Request A Standard Fix Version Creation + +A standard fix version creation is intended for packages that do not use streams and does not use a 4-part version number - usually determined by whether there is no JSON file available in the package directory and the package metadata file uses a 2 or 3-part version number. + +To request a fixed version, create an empty commit with the message `[AU packageName]`. This can be done by using the following command line call: `git commit --allow-empty-commit -m "[AU packageName]"` (replace packageName with the actual name of the package). Ensure you don't make any changes, as this can prevent your ability to push the commit. + +### Request A Standard Fix Version Creation For A Stream + +To request a standard fixed version for a stream, you need to figure out the name of the stream you want to force the fixed version of. All packages that support streams are expected to have a JSON file next to their metadata file that contains a list of the different streams and the last version found for that stream. Find the stream in this file, and make sure that the stream uses a 2 or 3-part version number. +Commonly, the highest version is located in the stream name `latest` (however, not always). It is also not guaranteed that all streams listed in the file are available. + +To request a fixed version, in this case, you create an empty commit with the message `[AU packageName\streamName]`. This can be done by using the following command line call: `git commit --allow-empty-commit -m "[AU packageName\streamName]` (replace packageName with the actual name of the package, and streamName with the name of the stream). Ensure you don't make any changes, as this can prevent your ability to push the commit. + +#### Request A Fixed Version Update + +If you need to update the same version the updater had previously submitted, or if the package you want uses a 4-part version number, you may need to specify the exact version you want to push. +It is crucial to note here that the version used will only change the version specified in the metadata file of the pushed package and not decide which version of the software will be pulled down from any upstream location. + +To create a fixed version update, you may use `[AU packageName:packageVersion]` for standard packages and `[AU packageName\streamVersion:packageVersion]` for stream packages using the same git command mentioned previously. Ensure you don't make any changes, as this can prevent your ability to push the commit. + +#### Requesting A Fix For A Package Using 4 Part Version Number + +If you need to create a fixed version for a package that already uses four parts of the version number, you must first add or update the updater script. +Before setting the `Version` parameter to the returned object in `au_GetLatest`, add a call to the function `Get-FixVersion`. This call should also include the parameter `-OnlyFixBelowVersion` that it set to the next patch version of the package. +See [gom-player](https://github.com/chocolatey-community/chocolatey-packages/blob/1849e4d17c66ff11cd48f4b8c9bf861add15bb68/automatic/gom-player/update.ps1#L38) for an example of this. Do note that you may need to create these changes as part of a PR if you cannot bypass the required checks in the repository. + +After committing this change, you can do a standard fix version creation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a30d80b29d..262dc40c541 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,31 +1,26 @@ -# Contributing +# Contributing Guidelines -    [Packages](#1-packages)                                                                                 [Source Files](#2-source-files)    [Teamwork](#3-teamwork) -    [Basics](#11-basics) - [Metadata](#12-metadata) - [AU Script](#13-au-script) - [UI Automation](#14-ui-automation) - ---- +Thank you for being so interested in contributing to the Chocolatey Community Packages repository. +This document details the expectations of what is needed when contributing to this repository and what rules all contributors need to follow. 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](#114-embed-a-package-if-allowed)). -* **High quality** - Packages should be resilient and should provide parameters where adequate. -* **Free** - Packages should be generally usable by anybody without any special prerequisites. +- **Stable** - Current and earlier versions should generally work so that you can depend on them. The most stable packages are those that are embedded. +- **High quality** - Packages should be resilient and provide adequate parameters. +- **Free** - Packages should generally be usable by anybody without any prerequisites. -To achieve those goals we are using the following priorities when adding new or maintaining existing packages: +To achieve these goals, we are using the following priorities when adding new or maintaining existing packages: 1. Cross-platform FOSS packages. -1. Windows only FOSS packages. -1. Freeware packages. -1. Commercial packages with unrestricted trials. +2. Windows-only FOSS packages. +3. Freeware packages. +4. Commercial packages with unrestricted trials. The following rules also apply: -1. When packages have the same priorities, software with higher number of users will generally be considered more important. -1. Applications without english localization are not accepted in this repository. -1. 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. +1. We will first consider software with more users when packages have the same priorities. +2. Applications must have English localization before we accept these in this repository. +3. The core maintainers may stop supporting a package after a discussion when the package requires too much maintenance or if there is not enough interest in the Community to work on the package. @@ -33,265 +28,382 @@ The following sections present complete set of guidelines, please read them care
Table of Contents -- [1. Packages](#1-packages) - - [1.1 Basics](#11-basics) - - [1.1.1 Conform to guidelines](#111-conform-to-guidelines) - - [1.1.2 Manual or automatic](#112-manual-or-automatic) - - [1.1.3 Naming](#113-naming) - - [1.1.4 Embed a package if allowed](#114-embed-a-package-if-allowed) - - [1.1.5 Support multiple versions](#115-support-multiple-versions) - - [1.1.6 Support multiple architectures](#116-support-multiple-architectures) - - [1.1.7 Clean code](#117-clean-code) - - [1.1.8 Set `softwareName`](#118-set-softwarename) - - [1.1.9 Test locally](#119-test-locally) - - [1.1.10 Dependency versions](#1110-dependency-versions) - - [1.1.11 Provide uninstaller only if needed](#1111-provide-uninstaller-only-if-needed) - - [1.1.12 Ensure compatibility with PowerShell v2+](#1112-ensure-compatibility-with-powershell-v2) - - [1.1.13 Chocolatey compatibility](#1113-chocolatey-compatibility) - - [1.2 Metadata](#12-metadata) - - [1.2.1 Obligatory metadata](#121-obligatory-metadata) - - [1.2.2 Obligatory tags](#122-obligatory-tags) - - [1.2.3 Informative description](#123-informative-description) - - [1.2.4 Add chocolatey-community among owners](#124-add-chocolatey-community-among-owners) - - [1.2.5 Provide icon](#125-provide-icon) - - [1.3 AU Script](#13-au-script) - - [1.3.1 Use `UseBasicParsing` [Optional]](#131-use-usebasicparsing-optional) - - [1.3.2 Do not download large files](#132-do-not-download-large-files) - - [1.3.3 Specify correct `NuspecVersion`](#133-specify-correct-nuspecversion) - - [1.4 UI Automation](#14-ui-automation) - - [1.4.1 Work on all locales](#141-work-on-all-locales) - - [1.4.2 Avoid brittle scripts](#142-avoid-brittle-scripts) -- [2. Source Files](#2-source-files) - - [2.1 Encoding](#21-encoding) - - [2.2 Code style](#22-code-style) -- [3. Teamwork](#3-teamwork) - - [3.1 Update CODEOWNERS](#31-update-codeowners) - - [3.2 Single package per pull request](#32-single-package-per-pull-request) - - [3.3 Open issues and pull request expiration](#33-open-issues-and-pull-request-expiration) - - [3.4 Understanding labels](#34-understanding-labels) +- [Etiquette](#etiquete) +- [Opening issues and discussions](#opening-issues-and-discussions) + - [Reporting a bug](#reporting-a-bug) + - [Reporting an outdated package](#reporting-an-outdated-package) + - [Requesting enhancements or new functionality](#requesting-enhancements-or-new-functionality) + - [Issue closing](#issue-closing) +- [Opening pull requests](#opening-pull-requests) + - [Pull request title](#pull-request-title) + - [Pull request body](#pull-request-body) +- [Conventions / Guidelines](#conventions--guidelines) + - [Manual or automatic](#manual-or-automatic) + - [Package types](#package-types) + - [Embedded packages](#embedded-packages) + - [Semi-Embedded packages](#semi-embedded-packages) + - [Remote packages](#remote-packages) + - [Metadata](#metadata) + - [Naming](#naming) + - [Dependency versions](#dependency-versions) + - [Conform to guidelines](#conform-to-guidelines) + - [Obligatory metadata](#obligatory-metadata) + - [Obligatory tags and categories](#obligatory-tags-and-categories) + - [Description](#description) + - [Maintainers](#maintainers) + - [Icons](#icons) + - [Chocolatey compatibility](#chocolatey-compatibility) + - [Chocolatey Scripts](#chocolatey-scripts) + - [UI Automation](#ui-automation) + - [Work on all locales](#work-on-all-locales) + - [Avoid brittle scripts](#avoid-brittle-scripts) + - [Source Files](#source-files) + - [Encoding](#encoding) + - [Code style](#code-style) + - [Update Script](#update-script) + - [Use `UseBasicParsing`](#use-usebasicparsing) + - [Do not download large files](#do-not-download-large-files) +- [FAQ](#faq) + - [Why do we automatically close issues?](#why-do-we-automatically-close-issues) + - [Why don't the repository maintainers fix the issues?](#why-do-not-the-repository-maintainers-fix-the-issues) + - [How can I create a fix version of a package?](#how-can-i-create-a-fix-version-of-a-package)
-# 1. Packages +## Etiquette -## 1.1 Basics +Ensure that all communications you make on this repository follow our [CODE OF CONDUCT][]. Please adhere to this document to avoid being banned from the repository. +In addition to the code of conduct document, ensure you do not unnecessarily [mention][@mention] other users when opening issues, discussions, or pull requests. Mentioning other users unneeded may lead to the current and future issues or pull requests not being addressed. -### 1.1.1 Conform to guidelines +## Opening Issues And Discussions -Conform with the [official package creation guidelines](https://docs.chocolatey.org/en-us/create/create-packages) and take a look at [quick start guide](https://docs.chocolatey.org/en-us/create/create-packages-quick-start) on how to create packages. +When opening issues about packages located in this repository, there are a few things you need to find out before opening said issue or discussion. -You should also know how to [deprecate a package](https://docs.chocolatey.org/en-us/community-repository/maintainers/deprecate-a-chocolatey-package). +1. Ensure the package you submit an issue or discussion about is available in this repository. + Packages in this repository will have the user `chocolatey-community` user listed under `Package Maintainer(s)` on the sidebar of the package page on community.chocolatey.org. +2. Determine if the issue will be about a bug, a new feature, an enhancement, an outdated package or a migration of a new package. + If you are still determining the issue type, open a general discussion about the package, or contact us through the community support channel for Chocolatey here: . +3. Use the templates associated by navigating to -### 1.1.2 Manual or automatic +### Reporting A Bug -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](https://github.com/majkinetor/au) module. +When reporting a bug, fill out the template for bug requests completely. The more information you can provide, including a list of steps to reproduce the bug found, the higher the likelihood that someone will fix the bug described. +Please include enough details about the bug to avoid the issue becoming ignored or closed if a maintainer can not reproduce the bug. +Ensure the issue title is prefixed `(packageName)` where `packageName` is the identifier of the package, and it should also contain a summary of the bug. -### 1.1.3 Naming +If you intend to fix this bug, you do not have to open an issue before submitting a pull request. Instead, see the section for [opening pull requests](#opening-pull-requests). -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* +### Reporting An Outdated Package -### 1.1.4 Embed a package if allowed +Before submitting a new issue for outdated packages, ensure there is no submitted (unapproved) version available on and that the new version has a valid stable new release. +Only open outdated package issues if there is a new stable release available. Issues for outdated pre-releases may be closed with no response given. +When reporting outdated packages, make sure you fill out the requested template completely. +Ensure the issue title is prefixed `(packageName)` where `packageName` is the identifier of the package, and it should also contain a summary of the bug. -_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`. +Unlike a bug report, you do not need a summary of the issue, but it should include the word `Outdated` instead. +For example, if you report the gimp package being outdated, the issue's title should be, at a minimum: `(gimp) Outdated`. -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. +### Requesting Enhancements Or New Functionality -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](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/qbittorrent), [less](https://github.com/majkinetor/au-packages/tree/master/less), [smplayer](https://github.com/majkinetor/au-packages/tree/master/smplayer). +Requesting new functionality for any package is not accepted as a direct pull request or a normal issue. +Any enhancement or functionality requests must be opened as a discussion. +Suppose the repository maintainers agree that the work should proceed. In that case, the maintainer will create an issue referencing the discussion. +A feature or enhancement will only be approved when it is known who will work on the implementation. If you wish to work on it, make sure to mention this in the initial discussion body. -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: +Issues created as a bug or an outdated report may be closed if it is determined to be a new functionality request or an enhancement to an existing package. You may then have to open a discussion about the package instead (though a maintainer may choose to convert the issue to a discussion, there is no guarantee). -- PDF of a signed license -- signed letter -- PDF of an email chain granting that permission +### Issue Closing + +We have an automated bot that goes through the issues created on the repository, marking issues as stale and closing any issues marked as stale. + +All issues are a candidate for becoming stale unless they have one of the following labels: + +- `Security / CVE` - We always want security-related issues completed. If these issues become stale, a new maintainer will be requested. +- `0 - Backlog` - A repository maintainer will work on these issues, but it is not scheduled when to do so. +- `1. - Ready for work` - A repository maintainer will work on these issues and has been scheduled when to work on it. +- `2. - Working` - A repository maintainer has started working on these issues. +- `3. - Review` - A repository maintainer has created a pull request for these issues. +- `5. - Push required` - A package that a maintainer must push to Chocolatey Community Repository to complete these issues has not yet been pushed. + +Additionally, if a user is assigned to an issue, it will not be automatically marked as stale or closed. Such issues should have an associated PR within 30 days, or the user needs to be unassigned, and it may become stale again. + +## Opening Pull Requests + +Pull requests fixing a bug or an outdated package do not need to have an associated issue. + +**Do not open a pull request when there is already an open pull request for the same issue or bug, as this will lead to your pull request being closed.** + +When opening a new pull request, you are required to input all the information requested by the pull request template used. +An existing issue marked by a maintainer with `up for grabs` or `0 - Backlog` must exist before opening a pull request for new features, enhancements, or migrating a package. +If an issue is available, but a maintainer has yet to mark it with one of the mentioned labels, or if a different user is assigned. Please comment on the issue, asking if you can work on it. Once a maintainer assigns you to the issue, you can work on it. +However, suppose you open a pull request without an associated issue. In that case, a maintainer may close the pull request immediately without a response. + +Your changes should only affect a single package unless the package(s) in question consists of a meta, `.install` and `.portable` package. In this case, you can submit all three packages in the same pull request. +There may also be other exceptions, but these will be on a case-by-case basis only when approved by a repository maintainer. -As an example take a look at the [activepresenter](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/activepresenter/legal) package. Embedding non-allowed binaries may have [legal repercussions](https://docs.chocolatey.org/en-us/information/legal). +Read the [Code Conventions](#code-conventions) before opening the pull request. -**NOTE**: 200MB is the maximum size of the package. Larger tools must be downloaded from a vendor site or mirror. +### Pull Request Title -### 1.1.5 Support multiple versions +Ensure the pull request title is prefixed `(packageName)` where `packageName` is the identifier of the package, and it should also contain a summary of the code changes. -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. +### Pull Request Body -### 1.1.6 Support multiple architectures +The existing template used for pull requests contains several sections you must fill out. If you have not filled out the template, a maintainer will not review the pull request, and a label with `0 - Waiting on user` will be added to the pull request. -* 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. -* If the same url is provided for both x64 bit and x32 bit versions, only use the `url` and the related parameters. Do not use `url64bit` and its related x64 bit parameters. +- `Description` - Explain the changes you have made as best as you can. +- `Motivation and Context` - Explain why you made the changes, and link any issues the pull request fixes in this section. +- `Screenshot` - This section is optional. However, it's always appreciated if you can show how the code added changes/fixes the behavior of the package. +- `Types of changes` - What changes have you made in the pull request - have you fixed a bug, implemented a new feature/enhancement, or has the code added broken existing functionality (i.e. is it incompatible with previous package versions)? +- `Checklist` - This section contains a list of tasks you have done before submitting the pull request and if additional work is needed. You are required to have done everything on the checklist when appropriate. You may skip the test environment check if you only modify `update.ps1` and only need to verify the description if you have made changes there. +- `Original Location` - This section is only relevant when migrating an existing package to the repository. Remove this section if you are not migrating a package to this repository. -### 1.1.7 Clean code +Before opening a pull request **make sure the package installs and uninstalls correctly** using the [Chocolatey Test Environment][] if you have made changes to files other than `update.ps1`. This environment is a reference machine to prevent the _it works on my box_ syndrome. The AU function `Test-Package -Vagrant` can speed this up. -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. +When a reviewer requires changes to the pull request, our automated bot will mark it with the label [`0 - Waiting on User`][Waiting Label]. If you fail to update the pull request within 14 days, it will be automatically closed. +If there is no need to update, but instead, a response is needed, then adding a comment on the threads created by the reviewer/code owner is enough. +Suppose you can't update the pull request within 14 days. In that case, temporarily closing the pull request may be better to allow other users to contribute a pull request if they have time. -If you created custom helper functions put them all in the `helpers.ps1` to keep installer clean and understandable ([example](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/virtualbox/tools)). +**NOTE: Do not add a comment to circumvent the automatic closure. Doing this may lead to the pull request being closed immediately instead.** -Chocolatey extension [chocolatey-core.extension](https://github.com/chocolatey-community/chocolatey-packages/tree/master/extensions/chocolatey-core.extension) provides functions that can make the code even more understandable. +## Conventions / Guidelines -### 1.1.8 Set `softwareName` +All packages in this repository are expected to pass all Requirement, Guideline and Suggestions checks on the Chocolatey Community Repository when possible. +All packages are also expected to follow the additional Conventions / Guidelines outlined in this section. -If the package uses [Install-ChocolateyPackage](https://github.com/chocolatey/choco/wiki/HelpersInstallChocolateyPackage) -`softwareName` should be set to represent software _Display Name_ correctly. You can use [myuninstaller](https://chocolatey.org/packages/myuninst) package to quickly determine it (it's called _Entry Name_ here). +Keep an eye on this section occasionally, as it will evolve and change without notifications. -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). +### Manual Or Automatic -### 1.1.9 Test locally +When working on packages in this repository, you must decide whether the package should be automatic or manual. +In most cases, a package should be automatic, as these can then update themselves without manual intervention when there is a new software release. + +The only time an automatic package should be a manual package is if the underlying software has not received any updates for three or more years or if it is impossible to automate. +New packages contributed/migrated to this repository should always be created as automatic packages. + +All automatic packages must use the [AU][AU Source] module and work in Windows PowerShell 5.x. PowerShell Core is not supported. + +The following metadata and script conventions are for automatic packages. However, manual packages need to follow the same rules where possible. + +### Package Types + +### Embedded Packages + +_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. Such packages must consist of two additional files in the `legal` directory within the source folder and shipped package - `VERIFICATION.txt` and `LICENSE.txt`. + +It is **recommended to create embedded packages** because they don't depend on an external site working, and substantially reduce the potential for network-related problems - 404 (file not found) problems and potential vendor bandwidth leaching issues are completely solved by embedding the binaries within the package. + +Refrain from committing binary files to this repository except for images, as it will cause the repository to become unnecessarily large when pulling down any changes. +The repository has a `.gitignore`, which excludes many popular binaries. Automatic packages use AU functions to produce packages that include binaries during the automated update procedure. +See the following packages as an example: [qbittorent][qbittorrent-source], [7zip.install][7zip Source], [transifex-cli][Transifex CLI Source]. + +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 -Before pull request **make sure package can install and uninstall correctly** using the [chocolatey test environment](https://github.com/chocolatey-community/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. +For example, look at the [activepresenter][Active Presenter Legals] package. Embedding non-allowed binaries may have [legal repercussions][Chocolatey Software Legal]. -_Although all PRs are tested on appveyor, all packages are expected to have been locally tested before the PR was submitted_ +**NOTE**: 200MB is the maximum size of a package on the Chocolatey Community Repository. The package must download larger tools from a vendor site or mirror or, if possible, create semi-embedded packages. -### 1.1.10 Dependency versions +### Semi-Embedded Packages -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 their process or incidentally install some package that uses newer version explicitly set, it will not automatically upgrade to the latest version. -1. 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. -1. When taking a dependency on **anything else, specify minimum or exact version**. +_Semi-Embedded_ packages are packages that only partially embed the software inside the nupkg archive. +A semi-embedded package is a common approach if including 32-bit and 64-bit binaries makes the package too big. +In these cases, the best approach, when possible, is to keep the 64-bit software still embedded while downloading any 32-bit software during installation if needed (as Windows is increasingly popular in a 64-bit arch). -### 1.1.11 Provide uninstaller only if needed +### Remote Packages -Packages should have uninstaller if auto uninstall doesn't work. +_Remote_ packages do not include any packaged software directly in the nupkg archive. Instead, it downloads what is necessary when a user installs the package. +A remote package is the most common type seen on Chocolatey Community Repository. It is the only valid approach if the packaged software does not allow redistribution and the software authors are unwilling to grant redistribution rights. +Additionally, when a package becomes too large to be uploaded to Chocolatey Community Repository, changing an embedded package to a remote one is valid if it is not possible to use a semi-embedded package. -### 1.1.12 Ensure compatibility with PowerShell v2+ +### Metadata -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. +This section details the conventions and guidelines for changing or updating each package's metadata. +Metadata information is in files with the `.nuspec` file extension or a `Readme.md` file. -For a reference of which cmdlets are available in PowerShell v2, please see the following link: http://adamringenberg.com/powershell2/ +#### Naming -### 1.1.13 Chocolatey compatibility +The package's name is taken from its root directory name for automatic packages. Suppose the original identifier of the existing package is not entirely lowercase. In that case, this needs to be overridden in an `update.ps1` script. +For manual packages, this is defined directly in the package metadata file. In general, this should always be in lowercase. However, existing packages should use the same casing as the original identifier. +This root directory name should always be in lowercase and follow the official [Chocolatey naming conventions](https://docs.chocolatey.org/en-us/create/create-packages#naming-your-package). -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. +#### Dependency Versions -## 1.2 Metadata +1. A minimum dependency version must be specified when adding a dependency. Without this, any version satisfies the dependency. That means it will only automatically upgrade to the latest version if someone upgrades the extension outside their process or incidentally installs some package that uses an explicitly set newer version. Changes to a package that does not specify a minimum or exact version will not be accepted. +2. When creating a dependency for virtual packages, specify an exact version range for the dependent package (_.install_ or _.portable). This version should be the same as that of the virtual package. An exact version in the metadata file will look like `[1.0.0]`. -### 1.2.1 Obligatory metadata +#### Conform To Guidelines - Make sure the following metadata is present and correct (unless it doesn't apply): `packageSourceUrl`, `projectSourceUrl`, `docsUrl`, `bugTrackerUrl`, `releaseNotes`, `licenseUrl`, `iconUrl`. +Conform with the [official package creation guidelines][Chocolatey Create Packages] and take a look at the [quick start guide][Chocolatey Quickstart Guide] on how to create packages. -`packageSourceUrl` **must not point to the repository root** but to the package root directory. +You should also know how to [deprecate a package][Chocolatey Package Deprecation] -### 1.2.2 Obligatory tags +#### Obligatory Metadata -Keep tags **lowercase** and separate them with spaces. For multi-word tags, use `-` between words (e.g. `cross-platform`). +You must fill in all possible elements in the metadata file when appropriate, including elements like `packageSourceUrl`, `projectSourceUrl`, `docsUrl`, `bugTrackerUrl`, `releaseNotes`, `licenseUrl` and `iconUrl` - even when one or more of these are made optional on Chocolatey Community Repository itself. If the software itself does not have any sufficient URLs to be used for these, then it can be omitted. -The following tags are mandatory to use if they apply: +You can ignore the description in the nuspec metadata file. Only the Readme.md must contain the description and is required. -|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 | +#### Obligatory Tags And Categories -**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`. +All tags and categories should be in lowercase and in the following order. +The tags specified should always be space delimited. -### 1.2.3 Informative description +- The first specified tag should always be a delimited dash name of the identifier of the package (excluding the suffixes `.install`, `.portable`, `.commandline` and `.app`). +- The second specified tag should be the category under which the packaged software falls. Only the following list of tags is allowed as the category tag (_NOTE: Existing packages may be missing a category tag, if you change a package that does not make use of one, a maintainer may ask you to include a category tag_) + - `addon` (for packaged software that is a plugin or addon for another application as well as PowerShell Modules) + - `browser` (For browser implementations like Google Chrome, Firefox, Microsoft Edge, Brave, and Opera.) + - `client` + - `driver` + - `editor` + - `extension` (only for Chocolatey Extensions) + - `games` + - `productivity` + - `programming` + - `server` + - `utility` + - `web` +- The third tag denotes the license type of the packaged software: + - `foss` (The packaged application is a free application with its source freely viewable by anyone) + - `freeware` (The packaged application is a free application, but its source is not available to be viewed) + - `oss` (The packaged application has its source freely viewable by anyone but requires payment for compiled binaries) + - `trial` (The packaged application is a commercial or paid application but includes a limited free trial) +- The fourth tag should be `cross-platform` if the application is available on multiple platforms. +- You may add additional tags after the fourth tag, which is recommended when possible. These tags should not be any previously mentioned tags used for categorization or licensing. -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**: +#### Description -|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 | +You can acquire the package description from the software author's website. It should include enough information about the application for those who know nothing about it. -### 1.2.4 Add chocolatey-community among owners +Additionally, there are a few descriptive headers that are required to be specified in the description as well. -Keep any existing owners and add `chocolatey-community` user before all others. +| Header Name | Meaning | +|----------------------|---------| +| `Features` | Bullet list that summarizes the available functionality of the packaged application | +| `Package Parameters` | Bullet list of the available package parameters that can be used when installing the package. This section can be omitted if there are no package parameters | +| `Notes` | Bullet list with any particular information about the software or package that the user should know about, e.g. recent breaking changes to the installation, uninstall or unusual edge cases | -### 1.2.5 Provide icon +#### Maintainers -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](https://github.com/chocolatey-community/chocolatey-packages/tree/master/icons) directory. +Maintainers of the package, in our case, are folk that have edited a package - either by being the original maintainer of the package or by contributing one or more changes to the package after it was added to the repository. +The metadata file should always include the package's current and historical maintainers. If you are editing a package, add yourself using a comma-delimited list format. +If the user `chocolatey-community` is not already specified as the package's maintainer, this user must be added as the first maintainer in the `owners` element. +One or more of the maintainers listed in the `owners` element should be similar to a name listed in our `CODE_OWNERS` file and will be considered the primary maintainer of the package. -If the package name ends with either `.install` or `.portable` those suffixes may be ignored in the icon name. +#### Icons -When icon is added to this folder **it will automatically be set** in the _nuspec file_ and README.md that contains `` tag. +A package must have an icon available if the packaged software has an icon. This 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`, the suffix may be ignored in the icon name. +When an icon is added to this folder with the correct name, it will **automatically** be set in the metadata file and the README file when our build server updates the package, if the metadata file contains an `` element. -**NOTE**: If the packaged software do not provide an icon, add the following to the package metadata file: ``. +**IMPORTANT: If no icon is available, the comment `` should be added to the metadata file** -## 1.3 AU Script +#### Chocolatey Compatibility -### 1.3.1 Use `UseBasicParsing` [Optional] +All packages are expected to be compatible with the oldest version of Chocolatey CLI we list as supported on our [Wiki Page][]. +If that is not possible, and the package needs a version of Chocolatey CLI released later, it will need to include a dependency for that Chocolatey CLI version. -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](https://github.com/chocolatey-community/chocolatey-packages/issues/382)). +### Chocolatey Scripts -### 1.3.2 Do not download large files +All PowerShell scripts are expected to be compatible with Windows PowerShell v2 through v5.1. If this is not possible, a dependency on the package `PowerShell` is required, with its minimum version set to the earliest version that the scripts in the package are expected to work with. -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`. +#### UI Automation -### 1.3.3 Specify correct `NuspecVersion` +Some installers do not provide silent arguments, and can be challenging to automate. -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: +Suppose 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 as in the [dropbox][Dropbox Package] package. In that case, you can use [AutoHotkey][Autohotkey Package]. -1. If you want to fix the existing CR package version for which no update is available at vendor specify the `NuspecVersion` the same as `RemoteVersion`. -1. 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. -1. 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. +Make [autohotkey.portable][Autohotekey Package] a dependency of the package. Community maintainers generally prefer AutoHotkey over [AutoIt][AutoIt Package] because AutoHotkey is more lightweight, FOSS, and more actively developed than AutoIt. -__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 +##### Work On All Locales -Some installers do not provide silent arguments and can be difficult to automate. +Scripts must work on every locale available for Windows. Be careful when using text strings for windows in the script that could differ in another language. -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](https://chocolatey.org/packages/dropbox) package, you can use [AutoHotkey](https://chocolatey.org/packages/autohotkey.portable). Make [autohotkey.portable](https://chocolatey.org/packages/autohotkey.portable) a dependency of the package. Prefer AutoHotkey over [AutoIt](https://chocolatey.org/packages/autoit.commandline), because AutoHotkey is more lightweight, FOS and more actively developed than AutoIt. +##### Avoid Brittle Scripts -### 1.4.1 Work on all locales +Do not create brittle scripts that work only when the user doesn't interfere. All script elements should be as precise as possible - for instance, instead of using the [Send][AHK Send Docs] function, which will work correctly only if the desired window is active, use [ControlSend][AHK ControlSend Docs] which doesn't require window activation or use [BlockInput][AHK BlockInput Docs] for short periods. -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. +#### Source Files -### 1.4.2 Avoid brittle scripts +##### Encoding -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](https://autohotkey.com/docs/commands/Send.htm) function which will work correctly only if the desired window is active, use [ControlSend](https://autohotkey.com/docs/commands/ControlSend.htm) which doesn't require window activation or use [BlockInput](https://autohotkey.com/docs/commands/BlockInput.htm) 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][]. -# 2. Source Files +##### Code Style -### 2.1 Encoding +Refrain from committing code with obvious styling problems such as irregular indentation levels, very long lines, too many comments, too many empty lines, and other styling issues. Please follow the [PoshCode PowerShell Practice and Style Guide][]. -Always __use UTF-8 without BOM__ for the `*.nuspec` and __UTF-8 with BOM__ for the `*.ps1` files. See [character encodings](https://docs.chocolatey.org/en-us/create/create-packages#character-encoding). +The project contains a [`.editorconfig`][Editorconfig Source] + file that you can use with many editors via [EditorConfig][] plugins. Ensure you use an editor with this support and have the support enabled. -### 2.2 Code style +Keep the package source files clean and remove outdated code and unnecessary comments. Comment on non-obvious code so that others can easily understand what it does. -Do not commit code with obvious styling problems such as irregular indentation levels, very long lines, too many comments, too many empty lines, etc. +### Update Script -The project contains [.editorconfig](https://github.com/chocolatey-community/chocolatey-packages/blob/master/.editorconfig) - file that can be used with many editors via [EditorConfig](http://editorconfig.org/) plugins. +Update scripts are the PowerShell scripts responsible for getting information about the software's most current version, where it can be acquired from, and how to modify the source code to produce the package. It is typically called `update.ps1`. +These scripts should be located in the root of the package directory, right next to the metadata (`.nuspec`) file. +The update script should be compatible with Windows PowerShell v5 and may not need to be compatible with PowerShell Core. -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. +#### Use `UseBasicParsing` When Possible -# 3. Teamwork +If you use the PowerShell cmdlet `Invoke-WebRequest` in the update script, always make sure to also pass in `-UseBasicParsing` to this cmdlet. There may be cases where using this parameter is not possible. Add a comment before the call about why `-UseBasicParsing` can not be used in these cases. +Any script that does not use this argument requires the Internet Explorer engine to be available and the web browser to have launched at least once before. -Good communication is essential so please take a look at [Code of Conduct](https://github.com/chocolatey/.github/blob/main/CODE_OF_CONDUCT.md) regarding it. +#### Do Not Download Large Files -### 3.1 Update CODEOWNERS +Unless a package installer/executable/archive needs some special handling (like reading the version from the file or something else not automatically handled by AU), do not download anything bigger than a few MB within `au_GetLatest` function. Usually, the files are downloaded during the updating process automatically or in the `au_BeforeUpdate` function. +Try finding alternatives to reading the version from the file when needed to prevent the need to download the file if no version elsewhere is available, like checking the headers of the response before doing a download. -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](https://github.com/chocolatey-community/chocolatey-packages/blob/master/.github/CODEOWNERS) file. +## FAQ -### 3.2 Single package per pull request +### Why Do We Automatically Close Issues? -All contributors should issue pull request containing single package. In special cases multiple packages per PR can be allowed. +The Chocolatey Packages repository is a shared repository that is worked on by the entire Chocolatey Community. When an issue lives for a long enough time to become stale, it needs more interest in the Community for the issue to become fixed. As there needs to be more interest in the Community, it is unlikely the issue will be fixed anytime soon, and it will instead be automatically closed. -### 3.3 Open issues and pull request expiration +### Why Do Not The Repository Maintainers Fix The Issues? -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](https://github.com/chocolatey-community/chocolatey-packages/issues?utf8=%E2%9C%93&q=label%3AUnresolved%20). +While there may be times that a repository maintainer will take steps to fix problems with a package, it is not the main reason for the repository maintainers here. +The repository maintainers' main tasks are to keep order in the repository, triage issues, ensure that the appropriate people review pull requests and that package changes are up to the quality expected for packages in the repository. -Pull Requests that have changes requested, and/or is marked with the label [0 - Waiting on User](https://github.com/chocolatey-community/chocolatey-packages/issues?q=is%3Aopen+label%3A%220+-+Waiting+on+User%22+sort%3Aupdated-desc) will be closed after 30 days of inactivity. +Repository maintainers are not responsible for fixing issues with the automated updater, automated checks on Chocolatey Community Repository that are failing, or implementing features or enhancements. +That does not mean it will not happen, but it is not one of their responsibilities. -### 3.4 Understanding labels +### How Can I Create A Fix Version Of A Package? -Most of the labels are self describing, here are few that require explanation: +A maintainer with repository write access must create a fixed package version. +If you do not have write access, please open an issue in our repository by filling out all the information being asked of you when using the [outdated template][Outdated Template] +Make sure the title of the issue says: `(packageName) Outdated` (_replace packageName with the name of the package_) +If you have write access to the repository and can push directly, see the appropriate section in the [COMMITTERS](COMMITTERS.md#providing-fix-versions) documentation file. -- [5 - Push required](https://github.com/chocolatey-community/chocolatey-packages/labels/5%20-%20Push%20required) -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](https://github.com/chocolatey-community/chocolatey-packages/labels/Wontfix) -Team doesn't think there is anything to fix here or that time required to fix it doesn't justify the benefit. -- [Unresolved](https://github.com/chocolatey-community/chocolatey-packages/labels/Unresolved) -The issue is unresolved - no feedback, no interest, and it probably expired. -- [0 - _Triaging](https://github.com/chocolatey-community/chocolatey-packages/labels/0%20-%20_Triaging) -Team is checking, confirming and measuring out the request. -- [Pending closure](https://github.com/chocolatey-community/chocolatey-packages/labels/Pending%20closure) -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](https://github.com/chocolatey-community/chocolatey-packages/labels/0%20-%20Waiting%20on%20User) -The team is waiting for somebody to respond. Until that happens, there will be no activity. +[@mention]: https://github.blog/2011-03-23-mention-somebody-they-re-notified/ +[7zip Source]: https://github.com/chocolatey-community/chocolatey-packages/tree/33ff3de69acedcac88f44b670fcb44b6422728db/automatic/7zip.install +[Active Presenter Legals]: https://github.com/chocolatey-community/chocolatey-packages/tree/33ff3de69acedcac88f44b670fcb44b6422728db/automatic/activepresenter/legal +[AHK BlockInput Docs]: https://www.autohotkey.com/docs/v2/lib/BlockInput.htm +[AHK ControlSend Docs]: https://www.autohotkey.com/docs/v2/lib/ControlSend.htm +[AHK Send Docs]: https://www.autohotkey.com/docs/v2/lib/Send.htm +[AU Source]: https://github.com/chocolatey-community/chocolatey-au +[Autohotkey Package]: https://community.chocolatey.org/packages/autohotkey.portable +[AutoIt Package]: https://community.chocolatey.org/packages/autoit.commandline +[character encodings]: https://docs.chocolatey.org/en-us/create/create-packages#character-encoding +[Chocolatey Create Packages]: https://docs.chocolatey.org/en-us/create/create-packages +[Chocolatey Package Deprecation]: https://docs.chocolatey.org/en-us/community-repository/maintainers/deprecate-a-chocolatey-package +[Chocolatey Quickstart Guide]: https://docs.chocolatey.org/en-us/create/create-packages-quick-start +[Chocolatey Software Legal]: https://docs.chocolatey.org/en-us/information/legal +[Chocolatey Test Environment]: https://github.com/chocolatey-community/chocolatey-test-environment +[Code of Conduct]: https://github.com/chocolatey-community/.github/blob/main/CODE_OF_CONDUCT.md +[Dropbox Package]: https://community.chocolatey.org/packages/dropbox +[EditorConfig Source]: https://github.com/chocolatey-community/chocolatey-packages/blob/master/.editorconfig +[EditorConfig]: https://editorconfig.org/ +[icons]: https://github.com/chocolatey-community/chocolatey-packages/tree/master/icons +[Outdated Template]: https://github.com/chocolatey-community/chocolatey-packages/issues/new?assignees=&labels=Outdated&template=outdated-report.yml&title=%28packageName%29+ +[PoshCode PowerShell Practice and Style Guide]: https://github.com/PoshCode/PowerShellPracticeAndStyle +[qbittorrent-source]: https://github.com/chocolatey-community/chocolatey-packages/tree/fa0d822f437b91fcd9be0730bfc8639098e3f3a9/automatic/qbittorrent +[Transifex CLI Source]: https://github.com/chocolatey-community/chocolatey-packages/tree/33ff3de69acedcac88f44b670fcb44b6422728db/automatic/transifex-cli +[Waiting Label]: https://github.com/chocolatey-community/chocolatey-packages/labels/0%20-%20Waiting%20on%20User +[Wiki Page]: https://github.com/chocolatey-community/chocolatey-packages/wiki/Supported-Chocolatey-CLI-versions