diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09fda76a19b2..e6bb10891fd1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing Guidelines 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 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: @@ -9,7 +9,7 @@ This repository presents **the latest and highest package standards**. The purpo - **High quality** - Packages should be resilient and should provide parameters where adequate. - **Free** - Packages should be generally usable by anybody without any prerequisites. -To aachieve these 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. 2. Windows only FOSS packages. @@ -18,8 +18,8 @@ To aachieve these goals we are using the following priorities when adding new or The following rules also apply: -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. +1. When packages 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. @@ -76,15 +76,15 @@ The following rules also apply: ## Etiquete 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. +In addition to the code of conduct document, make sure that you do not unnecessarily [mention](https://github.blog/2011-03-23-mention-somebody-they-re-notified/) 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. ## Opening issues and discussions 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. 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. + Packages located in this repository will have the user `chocolatey-community` 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 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. @@ -100,7 +100,7 @@ If you intend to fix this bug yourself, you do not have to open a issue before s ### Reporting an outdated package -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. +Before submitting a new issue for outdated packages, make sure there is not already a submitted (unapproved) version available on https://community.chocolatey.org, and that the new version has 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. @@ -108,63 +108,63 @@ As an example, if you report the gimp package being outdated the title of the is ### Requesting enhancements or new functionality -Requesting new functionality to any package is not accepted as direct pull requets, nor as normal issues. +Requesting new functionality for any package is not accepted as a direct pull request, nor as a normal issue. 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. +An issue with a reference to the discussion will be created once maintainers have agreed that work should proceed. +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. -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). +Issues created as a bug or as an outdated report may be closed immediately 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 convert the issue to a discussion, there is no guarantee). ### Issue closing -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. +We have an automated bot that goes through the issues created on the repository that will mark issues as stale, and close any issues marked as stale. -Most issues are considered when marking these as stale, with the exception of issues marked with one of the following labels: +All issues are considered for marking as stale, unless they have one of the following labels: -- `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. +- `Security / CVE` - This label is ignored by the bot 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, but it is not certain when it will be worked on. +- `1. - Ready 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 their 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. -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. +Additionally, if the issue has been assigned to a user it will not be automatically closed unless that user is unassigned. ## Opening pull requests 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. +When the pull request opened is for new features, enhancements, or migrating a package it is required that an issue already exists 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. -Pull requests fixing a bug or an outdated package do not need to have a issue associated with it. +Pull requests fixing a bug or an outdated package do not need to have an issue associated with it. -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. +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. -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. +Your changes should only affect a single package, unless the package(s) in question consist of a meta, `.install` and `.portable` package. 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. Make sure you read through the [Code Conventions](#code-conventions) as well before opening the pull request. ### Pull request title -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. +The pull request title should always be prefixed with the `(packageName)` where the package name is replaced with the name of the package this pull request is for. +This should be followed by a very short summary of the changes that are being made in the pull request (see previously accepted pull requests for examples). ### Pull request body -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. +The existing template used for pull requests contain several sections that are required to be filled out, without these items being filled correctly, the pull request will not be reviewed. - `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). +- `Screenshot` - This section is optional, but it's always appreciated if you are able to show how the code added changes/fixes the behaviour 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 has the code added broken existing functionality (i.e. 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. +- `Original Location` - This section is only relevant when migrating an existing package to the repository. If submitting a pull request that does not migrate a package from another location, this section should be removed. -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. +Before pull request **make sure the package installs and uninstalls correctly** using the [chocolatey test environment](https://github.com/chocolatey-community/chocolatey-test-environment). This environment is used as a reference machine to prevent _it works on my box_ syndrome. The AU function `Test-Package -Vagrant` can speed this up. -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. +After the pull request has been submitted and reviewed by 1 or more reviewers / code owners, if 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 this case, you will need to update the pull request 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. @@ -173,30 +173,30 @@ If you know you won't be able to update the pull request within 14 days, it may ## Conventions / Guidelines 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. +Additionally, all packages are also expected to follow the additional Conventions / Guidelines we have outlined in this section. ### Manual or automatic 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. +The only time an automatic package should possibly 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. 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. -The following metadata, and scripts conventions are for automatic packages, but manual packages are expected to follow the same rules when possible. +The following metadata and script conventions are for automatic packages, but manual packages are expected 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 and such packages must include two additional files in the directory `legal` - `VERIFICATION.txt` and `License.txt`. +_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 `legal` directory within the source folder and shipped package - `VERIFICATION.txt` and `LICENSE.txt`. -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. +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. 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. +The repository has a `.gitignore` which excludes many popular binaries. Automatic packages use AU functions to produce packages that include binaries during the 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). @@ -206,37 +206,37 @@ For software that explicitly doesn't allow redistribution via adequate license t - signed letter - PDF of an email chain granting that permission -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). +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). -**NOTE**: 200MB is the maximum size of the package. Larger tools must be downloaded from a vendor site or mirror. +**NOTE**: 200MB is the maximum size of a package on the Chocolatey Community Repository. 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. +_Semi-Embedded_ packages are packages that only partially embed the software inside of the nupkg archive. +This is a common approach being used when the size of the package has become too large, and the package currently includes both 32bit and 64bit versions of the software. +In these cases the best approach when possible is to keep the 64bit software still embedded, while downloading any 32bit software during installation if needed (as Windows is increasingly popular in 64bit arch). ### 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. +_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. +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 willing to grant 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 -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. +This section details the conventions and guidelines that are related to changing or updating metadata for each package. +Metadata is explicitly only the information that is defined for the package in its related `.nuspec` file. #### Naming -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 automatic packages the name of the package is taken from its root directory name. If the original identifier of the existing package is not fully 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. +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). #### Dependency versions -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]`. +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 an explicitly set newer version, it will not automatically upgrade to the latest version. Changes to a package that do not specify a minimum version, or exact version, not be accepted. +2. When creating a dependency for virtual packages, an exact version range should be used 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]`. #### Conform to guidelines @@ -246,7 +246,7 @@ You should also know how to [deprecate a package](https://docs.chocolatey.org/en #### Obligatory metadata -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. +When possible, all possible elements in the nuspec file should be filled. 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 can be omitted. #### Obligatory tags and categories @@ -255,8 +255,8 @@ The tags specified should always be space delimited. - 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) + - `addon` (for packaged software that is a plugin or addon for another application) + - `browser` (Specifically for browser implementations like Google Chrome, Firefox, Microsoft Edge, Brave, etc.) - `client` - `driver` - `editor` @@ -267,39 +267,39 @@ The tags specified should always be space delimited. - `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: +- The third tag denotes the license-type of the packaged software. 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) + - `trial` (The packaged application is a commercial or paid 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. #### Description -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. +The description of the package can usually be acquired from the software author's website, and should at a minimum include enough information about the application for those that know nothing about it. Additionally there are a few descriptive headers that are required to be specified in the description as well. | 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 | +| `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 special information about the software and/or package that the user should know about, e.g. recent breaking changes to the install, or unusual edge cases | #### Maintainers -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. +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 has been added to the repository. +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, using a comma-delimited list format. 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. #### Icons 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. +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. -**IMPORTANT: If there is no icon available, the comment `` is required to be specified in the metadata file** +**IMPORTANT: If there is no icon available, the comment `` should be added to the metadata file** #### Chocolatey compatibility @@ -309,23 +309,22 @@ If that is not possible, and the package needs a version of Chocolatey CLI that ### 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. +All PowerShell scripts are expected to be compatible with PowerShell v2 and later (not PowerShell 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. +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 as 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. In general, the community maintainers prefer AutoHotkey over [AutoIt](https://chocolatey.org/packages/autoit.commandline), because AutoHotkey is more lightweight, FOSS, and is more actively developed than AutoIt. ##### 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. +Scripts must work on every locale available for Windows, so be careful when using strings of text for windows in the script that could be different in another language. ##### 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. +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 periods of time. #### Source Files @@ -335,7 +334,7 @@ Always __use UTF-8 without BOM__ for the `*.nuspec` and __UTF-8 with BOM__ for t ##### 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. +Do not commit code with obvious styling problems such as irregular indentation levels, very long lines, too many comments, too many empty lines, etc. In general, please follow the [PoshCode PowerShell Practice and Style Guide](https://github.com/PoshCode/PowerShellPracticeAndStyle). 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. @@ -344,9 +343,9 @@ Keep the package source files clean and remove obsolete or outdated code and unn ### 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`. +Update scripts 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 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 PowerShell v5, but may not need to be compatible with PowerShell Core. +The update script should be compatible with PowerShell v5, and may not need to be compatible with PowerShell Core. #### Use `UseBasicParsing` @@ -367,7 +366,7 @@ The Chocolatey Packages repository is considered a shared repository that will b ### Why do not the repository maintainers fix the issues? 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. +The repository maintainers main tasks are to keep order in the repository, triage issues, make sure that pull requests are reviewed by the appropriate people, and changes to packages are up to the quality expected for packages in the repository. ### How can I create a fix version of a package?