diff --git a/.github/workflows/toc.yml b/.github/workflows/toc.yml index 377d9d2e8606..2414d602b4af 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 000000000000..0eb2505a750c --- /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 fix versions](#providing-fix-versions) + - [Request a normal fix version creation](#request-a-normal-fix-version-creation) + - [Request a normal 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 fix versions + +Before providing a fix version you need to determine what the existing version specified in the repository is, what type of version it makes use of and whether the package contains additional handling of creating fix versions. + +### Request a normal fix version creation + +A normal fix version creation is intended for packages that does not make use of streams, and does not use a 4 part version number. This is typically determined by whether there is no json file available in the package directory, and the package metadata file makes have a 2 or 3 part version number. + +To request a fix version in this case, 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). + +### Request a normal fix version creation for a stream + +To request a normal fix version for a stream you need to figure out what the name of the stream you want to force the fix version of is called. For all packages that support streams, it is expected to have a json file next to its metadata file that contains a list of the different streams, and the last version that was found for that stream. Find the stream in this file, make sure that the stream uses a 2 or 3 part version number. +It is common that the highest version being used is located in the stream name `latest` (however, not always). + +To then request a fix 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). + +#### Request a fixed version update + +If you need to update the same version that had been previously submitted, or if the package you want make use of a 4 part version number you may need to specify the exact version you want to push. +It is very important 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 that will be pulled down from any upstream location. + +To create a fixed version update you may use `[AU packageName:packageVersion]` for normal packages, and `[AU packageName\streamVersion:packageVersion]` for stream packages using the same git command mentioned previously. + +#### Requesting a fix for a package using 4 part version number + +If there is a need to create a fix version for a package that already uses 4 parts of the version number, you will need to add or update the update script first. +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. + +After committing this change, you can do a normal fix version creation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfa567d170ce..a9f1c53009e4 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 your interest in contributing to the Chocolatey Community Packages repository. +This document details the expectations of what is needed when contributing to this repository, and what 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** - When possible, current and earlier versions should generally work so you could depend on them. The most stable packages are those that are embedded. +- **High quality** - Packages should be resilient and should provide parameters where adequate. +- **Free** - Packages should be generally usable by anybody without any prerequisites. -To achieve those goals we are using the following priorities when adding new or maintaing existing packages: +To aachieve 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 guideliness, please read them carefully, especially since some of the rules are enforced and if broken will result in the failed PR build. +1. Whe npackages have the same priorities, software with higher number of users will generally be considered more important. +2. Applications without english localization are not accepted in this repository. +3. The core maintainers may decide to stop supporting a package after a discussion. This may happen if the package requires too much dedication during maintenance. @@ -33,224 +28,312 @@ The following sections present complete set of guideliness, please read them car
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) +- [Etiquete](#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 do not 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 +## Etiquete -## 1.1 Basics +Make sure that all communications you make on this repository follows our [CODE OF CONDUCT](https://github.com/chocolatey-community/.github/blob/main/CODE_OF_CONDUCT.md). Failure to adhere to this document may lead you to be banned from the repository. +In addition to the code of conduct document, make sure that you do not make unneeded reference to other users when opening issues, discussions or pull requests, doing so may lead to the issue or pull request being ignored by these users instead. -### 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. Make sure that the package you are submitting an issue or discussion about is located in this repository. + Packages located in this repository will have the user `chocolatey-community` listed as the maintainer on + the package details place on community.chocolatey.org. +2. Determine if the issue will be about a bug, a new feature, an enhancement, an outdated package or migration + of a new package. If you are uncertain about what type of issue it is, open a general discussion about the + package, or contact us through the community support channel for Chocolatey here: https://ch0.co/community. +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, make sure to fill out the template for bug requests completely. The more information you are able to provide, including a list of steps to reproduce the bug found, the higher the likelyhood that the bug will be fixed. +Failure to include enough details about the bug may lead to the issue being ignored, or closed if the bug can not be reproduced. +The title of the issue created should always be prefixed with `(packageName)` where packageName is replaced with the identifier of the package, and it should also contain a short summary of the bug. -### 1.1.3 Naming +If you intend to fix this bug yourself, you do not have to open a issue before submitting a pull request, see the section for [opening pull requests](#opening-pull-requests) instead. -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, make sure there is not already a submitted version available on https://community.chocolatey.org and that the new version have a valid stable new release. +Do not open outdated package issues if there is a new pre-release available, such issues may be closed without any response given. +As with the reporting of bugs, make sure to fill out the template for Outdated packages completely. +The title of such issues should always be prefixed with `(packageName)` where packageName is replaced with the identifier of the package. Unlike a bug report you do not need to have a summary of the issue, but instead it should include the word `Outdated` instead. +As an example, if you report the gimp package being outdated the title of the issue should be at a minimum: `(gimp) Outdated`. -_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`. +### Requesting enhancements or new functionality -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. +Requesting new functionality to any package is not accepted as direct pull requets, nor as normal issues. +Any enhancement or functionality requests must be opened as a discussion. +A new feature or enhancement once accepted will be created as a issue with a reference to the discussion once it has been approved. +A feature or enhancement will not be approved until it is known who will be working on the implementation, so if you wish to work on it make sure to mention this in the initial discussion body. -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). +Issues created as a bug or as an outdated report may be closed immediately if it is determined to be a new functionality, or an ehancement to existing packages, you may then have to open a discussion about the package instead (there are times a maintainer may convert the issue to a discussion, but this is no guarantee). -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: +### Issue closing -- PDF of a signed license -- signed letter -- PDF of an email chain granting that permission +We have an automated bot that goes through the issues created on the repository that will mark issues as stale, and close any issues that has been marked as stale. -As an example take a look at the [activepresenter](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/activepresenter/legal) package. Embeding non-allowed binaries may have [legal repercussions](https://docs.chocolatey.org/en-us/information/legal). +Most issues are considered when marking these as stale, with the exception of issues marked with one of the following labels: -**NOTE**: 200MB is the maximum size of the package. Larger tools must be downloaded from a vendor site or mirror. +- `Security / CVE` - This one is not considered as we always want security related issues resolved. +- `0 - Backlog` - This one is not considered as it will be worked on by a repository maintainer, butit is not certain when it will be worked on. +- `1. - Read for work` - This one is not considered as it will be worked on by a repository maintainer, and a date when the work is to be started has been set. +- `2. - Working` - This one is not considered as a repository maintainer has already started his/her work for the issue. +- `3. - Review` - This one is not considered as the work to complete the issue has already been submitted as a pull request. +- `5. - Push required` - This one is not considered as a package with the work for fixing the issue has not been submitted to community.chocolatey.org. +- `0 - Waiting on user` - This one requires additional input or changes from a user, it is typically used for pull requests but can be used for issues as well. If no changes or inputs are made, the issue will be automatically closed. -### 1.1.5 Support multiple versions +Additionally, if the issue has been assigned to a user it will not be automatically closed as well until that user is removed from the issue. -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. +## Opening pull requests -### 1.1.6 Support multiple architectures +When opening a new pull request it is required that you input all of the information requested by the pull request template being used. +When the pull request opened is for new features, enhancements or migrating a package it is required that a issue exists already before opening the pull request. +If no issue exists, or if an issue was opened after the pull request was opened it may be closed immediately without response. -* 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. +Pull requests fixing a bug or an outdated package do not need to have a issue associated with it. -### 1.1.7 Clean code +Do not open a pull request whene there is already an open pull request for the same issue or bug, as this will lead in your pull request becoming closed. -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. +Your changes should also only affect a single package, except if the package in question also consists of a meta, `.install` and `.portable` packages. In this case all three of the packages can be submitted in the same pull request. +There may be other exceptions as well, but these will be on a case by case basis, and only when approved by a repository maintainer. -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)). +Make sure you read through the [Code Conventions](#code-conventions) as well before opening the pull request. -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. +### Pull request title -### 1.1.8 Set `softwareName` +The pull request title should always be prefixed with the `(packageName)` where the package nam is replaced with the name of the this pull request is for. +Followed by a very short summary of the changes that are made in the pull request, see previously accepted pull requests for examples of what to use. -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). +### Pull request body -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). +The existing template used for pull requests contain several sections that are required to be filled out, without these itmes being filled correctly the code in the pull request will not be looked at. -### 1.1.9 Test locally +- `Description` - Explain as best as you can what the changes that you have made. +- `Motivation and Context` - Explain why the changes has been made, and link any issues that the pull request fixes in this section. +- `Screenshot` - This section is optional, but is always appreciated if you are able to show how the code added changes/fixes the behavior of the package. +- `Types of changes` - What type of changes have you made in the pull request, have you fixed a bug, implemented a new feature / enhancement or have the code added broken existing functionality (ie, it is incompatible with previous package versions). +- `Checklist` - This section contains a list of tasks that are required to be done before submitting the pull request. The only exception may be the two items regarding documentation which may not always be needed. +- `Original Location` - This section is only relevant when migrating a new package to the repository. If submitting a pull request that do not migrate a package, this section need to be removed instead. 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. -_Although all PR's are tested on appveyor, all packages are expected to have been locally tested before the PR was submitted_ +When the pull request has been submitted, and looked over by 1 or more reviewers / code owners and it requires changes, the pull request will be marked with the label [`0 - Waiting on User`](https://github.com/chocolatey-community/chocolatey-packages/labels/0%20-%20Waiting%20on%20User) in which case you need to update the pull request again within 14 days. +If the pull request is not updated within this time, the pull request 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. +If you know you won't be able to update the pull request within 14 days, it may be better to temporarily close the issue to allow other users to contribute a pull request if they have time. +**NOTE: Do not add a comment just to circumvent the automatic closure, this may lead the pull request to be closed immediately instead** -### 1.1.10 Dependency versions +## Conventions / Guidelines -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. -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**. +All packages in this repository are expected to pass all Requirement, Guideline and Suggestions checks on the Chocolatey Community Repository when it is possible. +Additionally, all packages are also expected to following the additional Conventions / Guidelines we have outlined in this section. -### 1.1.11 Provide uninstaller only if needed +### Manual or automatic -Packages should have uninstaller if auto uninstall doesn't work. +When working on packages in this repository, a decision must be made whether the package should be an automatic or manual package. +In most cases it is preferable that a package is made automatic, as these can then be updated without doing manual changes when there is a new release of the +software that is being packaged. +The only time an automatic package should be considered to be a manual package is if the underlying software that is being packaged has not been updated for 3 or more years. +New packages contributed/migrated to this repository should always be created as automatic packages. -### 1.1.12 Ensure compatibility with PowerShell v2+ +All automatic packages are expected to make use of the [AU](https://github.com/chocolatey-community/chocolatey-au) module, and work in Windows PowerShell 5.x, PowerShell Core is not supported. -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. +The following metadata, and scripts conventions are for automatic packages, but manual packages are expected to follow the same rules when possible. -For a reference of which cmdlets are available in PowerShell v2, please see the following link: http://adamringenberg.com/powershell2/ +### Package types -### 1.1.13 Chocolatey compatibility +### Embedded packages -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. +_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`. -## 1.2 Metadata +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. -### 1.2.1 Obligatory metadata +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), +[7zip.install](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/7zip.install), [transifex-client](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/transifex-client). - Make sure the following metadata is present and correct (unless it doesn't apply): `packageSourceUrl`, `projectSourceUrl`, `docsUrl`, `bugTrackerUrl`, `releaseNotes`, `licenseUrl`, `iconUrl`. +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: -`packageSourceUrl` **must not point to the repository root** but to the package root directory. +- PDF of a signed license +- signed letter +- PDF of an email chain granting that permission -### 1.2.2 Obligatory tags +As an example take a look at the [activepresenter](https://github.com/chocolatey-community/chocolatey-packages/tree/master/automatic/activepresenter/legal) package. Embeding non-allowed binaries may have [legal repercussions](https://docs.chocolatey.org/en-us/information/legal). + +**NOTE**: 200MB is the maximum size of the package. Larger tools must be downloaded from a vendor site or mirror. + +### Semi-Embedded packages + +_Semi-Embedded_ packages are packages that only partially embeds the software inside of the nupkg archive. +This is a common approach being used when the size of the package has become to large, and it includes both 32bit and 64bit softwares. +In these cases the best approach when possible is to keep the 64bit softwares still embedded, while downloading any 32bit softwares during installation if needed. + +### Remote packages + +_Remote_ packages does not include any packaged software directly in the nupkg archive, instead it downloads what is necessary when a user installs the package. +This is the most common type seen on the Chocolatey Community Repository, and is the only valid approach if the software being packaged does not allow for it to be redistributed and the software authors are not granting and redistribution rights. +Additionally, when a package becomes too large to be uploaded to Chocolatey Community Repository it is valid to change an embedded package to a remote package. + +### Metadata -Keep tags **lowercase**. Use `-` between words. The following tags are mandatory to use if they apply: +This section details the conventions and guideliens that are related to changing or updating metadata for each package. +Metadata are explicitly only the information that is defined for the package in its related `.nuspec` file. -|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 | +#### Naming -**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`. +For automatic packages the name of the package is taken from its root directory name, if the original idenifier of the existing package is not in lowercase this needs to be overridden in an `update.ps1` script. +For manual packages this is defined directly in the package nuspec file, in general this should also be in lowercase but for existing packages it should use the same casing as the original identifier. +This root directory name should always be in lower case and follow the official Chocolatey naming conventions: https://docs.chocolatey.org/en-us/create/create-packages#naming-your-package. -### 1.2.3 Informative description +#### Dependency versions -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**: +1. When taking a dependency on an extension, a minimum version of that dependency must be specified. 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 explictly set, it will not automatically upgrade to the latest version. Changes to a package that does not specify a minimum version, or exact version is will not be accepted. +2. When creating a dependency for virtual packages, a exact version range should be used for the dependent package (_.install_ or _.portable), which should be the same as that of the virtual package. An exact version range in the metadata file will look like `[1.0.0, 1.0.0]`. -|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 | +#### Conform to guidelines -### 1.2.4 Add chocolatey-community among owners +Conform with the [official package creation guidelines](1754-Update-Guidelines-and-code-to-reflect-new-procedures) and take a look at the [quick start guide](https://docs.chocolatey.org/en-us/create/create-packages-quick-start) on how to create packages. -Keep any exisiting owners and add `chocolatey-community` user before all others. +You should also know how to [deprecate a package](https://docs.chocolatey.org/en-us/create/create-packages-quick-start) -### 1.2.5 Provide icon +#### Obligatory metadata -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. +When possible, all elements in the nuspec file is obligated to be made use of. This includes 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 examples, then it is fine to be omitted. -If the package name ends with either `.install` or `.portable` those suffixes may be ignored in the icon name. +#### Obligatory tags and categories -When icon is added to this folder **it will automatically be set** in the _nuspec file_ and README.md that contains `` tag. +All tags and categories should be in lowercase, and should be in the following order. +The tags specified should always be space delimited. -**NOTE**: If the packaged software do not provide an icon, add the following to the package metadata file: ``. +- The first specified tag should always be a dash delimited name of the identifier of the package (excluding the suffixes `.install`, `.portable`, `.commandline` and `.app`). +- The second specified tag should be the category that the packaged software falls under. Only the following list of tags are allowed to be used 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, you will be asked to include a category tag_) + - `addon` (For packaged softwares that are plugins or addons for other applications) + - `browser` (Specifically for browser implementations, like Google Chrome, Firefox, Microsoft Edge, Brave, Etc) + - `client` + - `driver` + - `editor` + - `extension` (only for Chocolatey Extensions) + - `games` + - `productivity` + - `programming` + - `server` + - `utility` + - `web` +- The third tag denotes what type of application is being packages when it comes to license related information. These tags can be summarized with the following: + - `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) + - `trial` (The packaged application is a commercial or payed application, but includes a limited free trial that can be used) +- If the application is available on multiple platforms, the fourth tag should be `cross-platform`. +- More tags can be added and is recommended to be added when possible, these tags should not be of any of the previously mentioned tags used for categorization or licensing. -## 1.3 AU Script +#### Description -### 1.3.1 Use `UseBasicParsing` [Optional] +The description of the package can usually be acquired from the software authors website, and should at a minimum include enough information about the application for those that knows nothing of them to be able to give a decision if the application is for them or not. -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)). +Additionally there are a few descriptive headers that are required to be specified in the description as well. -### 1.3.2 Do not download large files +| Header Name | Meaning | +|----------------------|---------| +| `Features` | Bullet list that sumarrizes the availbale 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 is no package parameters | +| `Notes` | Bullet list with any special information to the user about the software and/or package that they need to know about | -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_GetLatest` function. Normally, the files are downloaded during the embeding process by the `au_BeforeUpdate`. +#### Maintainers -### 1.3.3 Specify correct `NuspecVersion` +Maintainers of the package in our case are users that have edited a package, either by being the main maintainer of the package or contributed one or more changes to the package. +The metadata file should always include both current and historical maintainers of the package, if you are editing a package make sure to add yourself as the last maintainer colon delimeted list. +If the user `chocolatey-community` is not already specified as the maintainer of the package, this user must be added as the first maintainer in the `owners` element. +One or more maintainers of the maintainers listed in the `owners` element should be equal to a similar name listed in our `CODE_OWNERS` file, and will be considered the main maintainer of the package. -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: +#### Icons -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`. -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 explicitelly set. +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](https://github.com/chocolatey-community/chocolatey-packages/tree/master/icons) directory. +If the package name ends with either `.install`, `.portable` those suffixes may be ignored in the icon name. +When an icon is added to this folder with the correct name, it wwill **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__: 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 +**IMPORTANT: If there is no icon available, the comment `` is required to be specified in the metadata file** + +#### Chocolatey compatibility + +All packages are expected to be compatible with the version of Chocolatey CLI that was available 12 months earlier than the last change of the package. +With that, it means that if you make a change to the nuspec, or one of the package scripts on January 12th, 2023 it should be compatible with Chocolatey CLI 0.11.3 and later released versions. +If that is not possible, and the package needs a version of Chocolatey CLI that was released later, it will need to include a dependency for that Chocolatey CLI version. + +### Chocolatey Scripts + +All PowerShell scripts are expected to be compatible with PowerShell v2 and later (not PowerShel Core). 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 is expected to work with. + +**TODO: This section needs to be updated, and is a copy-paste from earlier guidelines** + +#### 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](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. -### 1.4.1 Work on all locales +##### 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 +##### 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](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. -# 2. Source Files +#### Source Files -### 2.1 Encoding +##### Encoding 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). -### 2.2 Code style +##### Code style Do not commit code with obvious styling problems such as irregular indentation levels, very long lines, too many comments, too many empty lines, etc. @@ -259,37 +342,36 @@ The project contains [.editorconfig](https://github.com/chocolatey-community/cho 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 +### Update Script + +An update script are the PowerShell scripts responsible for getting the information about what the most current version of the software is, where it can be acquired from and 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 PowerShell v5, but may not need to be compatible with PowerShell Core. -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. +#### Use `UseBasicParsing` -### 3.1 Update CODEOWNERS +If you use the PowerShell cmdlet in the update script, always make sure to also pass in `-UseBasicParsing` to this script. There may be cases where using this parameter is not possible, in these cases a comment right before the call should be specified about why `-UseBasicParsing` can not be used. +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. -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. +#### Do not download large files -### 3.2 Single package per pull request +Unless a package installer/executable/archive needs some special handling (like the need to read the version from the file, or something else not automatically handled by AU), anything bigger than a few MB should never be downloaded within `au_GetLatest` function. Normally, 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. -All contributors should issue pull request containing single package. In special cases multiple packages per PR can be allowed. +## FAQ -### 3.3 Open issues and pull request expiration +### Why do we automatically close 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). +The Chocolatey Packages repository is considered a shared repository that will be worked on by the entire Chocolatey Community. When an issue lives for long enough time to become stale, it is considered to not be enough interest in the community for the issue to become fixed. As such it is more appropriate to close the issue than continue to keep issues open that will not be worked on. -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. +### Why do not the repository maintainers fix the issues? -### 3.4 Understanding labels +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 and making sure that pull requests becomes reviewed by the appropriate people and changes to packages is up to the quality expected for packages in the repository. -Most of the labels are self describing, here are few that require explanation: +### How can I create a fix version of a package? -- [5 - Push required](https://github.com/chocolatey-community/chocolatey-packages/labels/5%20-%20Push%20required) -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](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 benfit. -- [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 life time. This is annoucement that issue will soon get closed in 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. +A fix version of a package must be created by a maintainer in the repository that have write access to the repository. +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 following template: https://github.com/chocolatey-community/chocolatey-packages/issues/new?assignees=&labels=Outdated&template=outdated-report.yml&title=%28packageName%29+ +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#providing-fix-versions] documentation file.