From f304ebd87ae21e279ab08459b084657fea6ab530 Mon Sep 17 00:00:00 2001 From: Cory Knox Date: Mon, 18 Mar 2024 12:56:13 -0700 Subject: [PATCH 1/6] (#49) Add migration page --- Migrating-AU-to-Chocolatey-AU.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 Migrating-AU-to-Chocolatey-AU.md diff --git a/Migrating-AU-to-Chocolatey-AU.md b/Migrating-AU-to-Chocolatey-AU.md new file mode 100644 index 00000000..08908f7d --- /dev/null +++ b/Migrating-AU-to-Chocolatey-AU.md @@ -0,0 +1,27 @@ +# Migrating From AU To Chocolatey AU + +With the [`1.0.0` release] of Chocolatey AU, there is a need to migrate to the new package name. + +How you migrate from AU to Chocolatey AU will depend on how you used AU in your repository. Below are some scenarios, if you encounter a scenario not yet covered, please reach out in the [Chocolatey Community]. + +## Your Repository Currently Clones The [Original AU Repository] + +If you are cloning the [original AU repository] and building the module from there, you will want to update to clone the Chocolatey Community Chocolatey AU repository: `https://github.com/chocolatey-community/chocolatey-au.git` instead. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. + +## Your Repository Installs AU From The [Chocolatey Community Repository] + +If you are installing `AU` from the [Chocolatey Community Repository], you will want to update it to `choco install chocolatey-au --confirm` instead of `choco install au --confirm`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. + +## Your Repository Installs AU From The [Powershell Gallery] + +If you are installing `AU` from the [PowerShell Gallery], you will want to update it to `Install-Module Chocolatey-AU` instead of `Install-Module AU`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. + +## Updating Your Update Scripts + +Once you have updated your repository to use the new module name, you will need to update your `update.ps1` scripts to use the new module name. This is as simple as replacing `AU` with `Chocolatey-AU` for any call to `Import-Module`, or any `#requires -Modules` in you `update.ps1` scripts. + +[`1.0.0` release]: https://github.com/chocolatey-community/chocolatey-au/releases/tag/1.0.0 +[Chocolatey Community]: https://ch0.co/community +[Chocolatey Community Repository]: https://community.chocolatey.org/ +[PowerShell Gallery]: https://powershellgallery.com +[Original AU Repository]: https://github.com/majkinetor/au/ From 7c3666fa919306cbb843a7f359f1f552b5b3ca33 Mon Sep 17 00:00:00 2001 From: Cory Knox Date: Wed, 20 Mar 2024 07:46:51 -0700 Subject: [PATCH 2/6] (#49) Address review comments --- Migrating-AU-to-Chocolatey-AU.md | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/Migrating-AU-to-Chocolatey-AU.md b/Migrating-AU-to-Chocolatey-AU.md index 08908f7d..a58c7540 100644 --- a/Migrating-AU-to-Chocolatey-AU.md +++ b/Migrating-AU-to-Chocolatey-AU.md @@ -1,27 +1,21 @@ -# Migrating From AU To Chocolatey AU +# Migrating From `AU` To `Chocolatey-AU` -With the [`1.0.0` release] of Chocolatey AU, there is a need to migrate to the new package name. +With the [`1.0.0` release](https://github.com/chocolatey-community/chocolatey-au/releases/tag/1.0.0) of `Chocolatey-AU`, there is a need to migrate to the new package name. -How you migrate from AU to Chocolatey AU will depend on how you used AU in your repository. Below are some scenarios, if you encounter a scenario not yet covered, please reach out in the [Chocolatey Community]. +How you migrate from `AU` to `Chocolatey-AU` will depend on how you used `AU` in your repository. Below are some scenarios, if you encounter a scenario not yet covered, please reach out in the [Chocolatey Community](https://ch0.co/community). -## Your Repository Currently Clones The [Original AU Repository] +## Your Repository Currently Clones The Original `AU` Repository -If you are cloning the [original AU repository] and building the module from there, you will want to update to clone the Chocolatey Community Chocolatey AU repository: `https://github.com/chocolatey-community/chocolatey-au.git` instead. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. +If you are cloning the [original `AU` repository](https://github.com/majkinetor/au/) and building the module from there, you will want to update to clone the Chocolatey Community `Chocolatey-AU` repository: `https://github.com/chocolatey-community/chocolatey-au.git` instead. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. -## Your Repository Installs AU From The [Chocolatey Community Repository] +## Your Repository Installs AU From The Chocolatey Community Repository -If you are installing `AU` from the [Chocolatey Community Repository], you will want to update it to `choco install chocolatey-au --confirm` instead of `choco install au --confirm`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. +If you are installing `AU` from the [Chocolatey Community Repository](https://community.chocolatey.org/), you will want to update it to `choco install chocolatey-au --confirm` instead of `choco install au --confirm`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. -## Your Repository Installs AU From The [Powershell Gallery] +## Your Repository Installs AU From The Powershell Gallery -If you are installing `AU` from the [PowerShell Gallery], you will want to update it to `Install-Module Chocolatey-AU` instead of `Install-Module AU`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. +If you are installing `AU` from the [PowerShell Gallery](https://powershellgallery.com), you will want to update it to `Install-Module Chocolatey-AU` instead of `Install-Module AU`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. ## Updating Your Update Scripts -Once you have updated your repository to use the new module name, you will need to update your `update.ps1` scripts to use the new module name. This is as simple as replacing `AU` with `Chocolatey-AU` for any call to `Import-Module`, or any `#requires -Modules` in you `update.ps1` scripts. - -[`1.0.0` release]: https://github.com/chocolatey-community/chocolatey-au/releases/tag/1.0.0 -[Chocolatey Community]: https://ch0.co/community -[Chocolatey Community Repository]: https://community.chocolatey.org/ -[PowerShell Gallery]: https://powershellgallery.com -[Original AU Repository]: https://github.com/majkinetor/au/ +Once you have updated your repository to use the new module name, you will need to update your `update.ps1` scripts to use the new module name. This is as simple as replacing `AU` with `Chocolatey-AU` for any call to `Import-Module`, or any `#requires -Modules` in your scripts. From bb1782018edbcd2bd41b7bf6af365c1745af4468 Mon Sep 17 00:00:00 2001 From: Cory Knox <30301021+corbob@users.noreply.github.com> Date: Wed, 20 Mar 2024 14:22:14 -0700 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Paul Broadwith --- Migrating-AU-to-Chocolatey-AU.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/Migrating-AU-to-Chocolatey-AU.md b/Migrating-AU-to-Chocolatey-AU.md index a58c7540..a0347b49 100644 --- a/Migrating-AU-to-Chocolatey-AU.md +++ b/Migrating-AU-to-Chocolatey-AU.md @@ -2,20 +2,21 @@ With the [`1.0.0` release](https://github.com/chocolatey-community/chocolatey-au/releases/tag/1.0.0) of `Chocolatey-AU`, there is a need to migrate to the new package name. -How you migrate from `AU` to `Chocolatey-AU` will depend on how you used `AU` in your repository. Below are some scenarios, if you encounter a scenario not yet covered, please reach out in the [Chocolatey Community](https://ch0.co/community). +How you migrate from `AU` to `Chocolatey-AU` will depend on how you used `AU` in your repository. Below are some scenarios, but if you encounter a scenario not yet covered, please reach out in the [Chocolatey Community](https://ch0.co/community). -## Your Repository Currently Clones The Original `AU` Repository +## Your Repository Currently Clones the Original `AU` Repository -If you are cloning the [original `AU` repository](https://github.com/majkinetor/au/) and building the module from there, you will want to update to clone the Chocolatey Community `Chocolatey-AU` repository: `https://github.com/chocolatey-community/chocolatey-au.git` instead. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. +If you are cloning the [original `AU` repository](https://github.com/majkinetor/au/) and building the module from there, you will want to update to clone the Chocolatey Community `Chocolatey-AU` repository: `https://github.com/chocolatey-community/chocolatey-au.git` instead. Once that has been done, you will want to [amend your update scripts](#amending-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. -## Your Repository Installs AU From The Chocolatey Community Repository -If you are installing `AU` from the [Chocolatey Community Repository](https://community.chocolatey.org/), you will want to update it to `choco install chocolatey-au --confirm` instead of `choco install au --confirm`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. +## Your Repository Installs AU From the Chocolatey Community Repository -## Your Repository Installs AU From The Powershell Gallery +If you are installing `AU` from the [Chocolatey Community Repository](https://community.chocolatey.org/), you will want to update it to `choco install chocolatey-au --confirm` instead of `choco install au -y`. Once that has been done, you will want to [update your update scripts](#amending-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. -If you are installing `AU` from the [PowerShell Gallery](https://powershellgallery.com), you will want to update it to `Install-Module Chocolatey-AU` instead of `Install-Module AU`. Once that has been done, you will want to [update your update scripts](#updating-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. +## Your Repository Installs AU From the Powershell Gallery -## Updating Your Update Scripts +If you are installing `AU` from the [PowerShell Gallery](https://powershellgallery.com), you will want to amend your code to `Install-Module Chocolatey-AU` from `Install-Module AU`. Once that has been done, you will want to [amend your update scripts](#amending-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. -Once you have updated your repository to use the new module name, you will need to update your `update.ps1` scripts to use the new module name. This is as simple as replacing `AU` with `Chocolatey-AU` for any call to `Import-Module`, or any `#requires -Modules` in your scripts. +## Amending Your Update Scripts + +Once your repository uses the new module name, you will need to amend your `update.ps1` scripts to use the new module name. This is as simple as replacing `AU` with `Chocolatey-AU` for the `Import-Module` calls, or any `#requires -Modules` in your scripts. From 137e053e06f63f8da8129bf97882db38fa3e0cf6 Mon Sep 17 00:00:00 2001 From: Cory Knox Date: Fri, 5 Apr 2024 18:52:05 -0700 Subject: [PATCH 4/6] (#49) Update names to Chocolatey-AU Update the names in README.md to Chocolatey-AU. Link to the files within the repository using relative links instead of directly to the repository. This will allow links to go to the correct versions instead of just the latest version. --- Plugins.md | 35 +++++++++++++++--------------- README.md | 63 ++++++++++++++++++++++++++---------------------------- 2 files changed, 47 insertions(+), 51 deletions(-) diff --git a/Plugins.md b/Plugins.md index 5b9831d7..21b0c748 100644 --- a/Plugins.md +++ b/Plugins.md @@ -5,11 +5,11 @@ --- -[AU plugins](https://github.com/majkinetor/au/blob/master/AU/Plugins) are [configured](https://github.com/majkinetor/au#plugins) using parameters passed in the HashTable contained in the Options under the key that is named by the plugin. So,`$Options.xyz=@{...}` is a plugin if `xyz.ps1` exists in a directory pointed to by the `PluginPath` updateall option. The AU will then run this script and pass it `$Options.xyz` HashTable as plugin specific options. AU comes with several integrated plugins that are described bellow. +[Chocolatey-AU plugins](Plugins) are [configured](README.md#plugins) using parameters passed in the HashTable contained in the Options under the key that is named by the plugin. So,`$Options.xyz=@{...}` is a plugin if `xyz.ps1` exists in a directory pointed to by the `PluginPath` updateall option. The Chocolatey-AU will then run this script and pass it `$Options.xyz` HashTable as plugin specific options. Chocolatey-AU comes with several integrated plugins that are described bellow. Default [update_all.ps1](https://github.com/majkinetor/au-packages-template/blob/master/update_all.ps1) uses environment variables to configure some options. If you use [AppVeyor](https://github.com/majkinetor/au/wiki/AppVeyor) set those variables in the [.appveyor.yml](https://github.com/majkinetor/au-packages-template/blob/master/.appveyor.yml) and to run it locally use [update_vars.ps1](https://github.com/majkinetor/au-packages-template/blob/master/update_vars_default.ps1). -## [Gist](https://github.com/majkinetor/au/blob/master/AU/Plugins/Gist.ps1) +## [Gist](src/Plugins/Gist.ps1) **Upload one or more files to gist**. @@ -20,14 +20,14 @@ To set up plugin to create gist under your user name you need to give it your gi * Create [Github personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) and **make sure token has _gist_ scope selected**. Authenticating with username and password isn't supported for security reasons. Set it as `$Env:github_api_key` environment variable. -## [Git](https://github.com/majkinetor/au/blob/master/AU/Plugins/Git.ps1) +## [Git](src/Plugins/Git.ps1) **Persist modified files**. -* To use it locally, just ensure `git push` doesn't require credentials and dont set any environment variables. +* To use it locally, just ensure `git push` doesn't require credentials and dont set any environment variables. * To use on build server such as [[AppVeyor]], specify `$Env:username` and `$Env:password`. If you host git repository on Github its preferable to use personal access token. You can use the same token as with gist as long as _**public repo**_ scope is activated. -## [GitLab](https://github.com/majkinetor/au/blob/master/AU/Plugins/GitLab.ps1) +## [GitLab](src/Plugins/GitLab.ps1) **Persist modified files**. @@ -36,13 +36,13 @@ To set up plugin to create gist under your user name you need to give it your gi * `pushurl` must be a full HTTP(S) URL to the repo; the same one you would use to clone it. Internal plugin logic will use this to reconstruct a compatible URL. -## [GitReleases](https://github.com/majkinetor/au/blob/master/AU/Plugins/GitReleases.ps1) +## [GitReleases](src/Plugins/GitReleases.ps1) **Creates Github release for updated packages**. -* It is recommended to add the following line `skip_tags: true` in the `appveyor.yml` file to prevent tags from being built. While it may not be necessary, this is used to prevent packages from being submitted again when `[AU]` or `[PUSH]` is being used in the commit header message. +* It is recommended to add the following line `skip_tags: true` in the `appveyor.yml` file to prevent tags from being built. While it may not be necessary, this is used to prevent packages from being submitted again when `[Chocolatey-AU]` or `[PUSH]` is being used in the commit header message. -## [Gitter](https://github.com/majkinetor/au/blob/master/AU/Plugins/Gitter.ps1) +## [Gitter](src/Plugins/Gitter.ps1) **Setup project to submit gitter status** @@ -51,7 +51,7 @@ To set up plugin to create gist under your user name you need to give it your gi 2. Select a `Custom` Integration 3. Copy the unique webhook url listed in the dialog. 4. Update your appveyor environment variable with your unique webhook, and set the name to `gitter_webhook`. - 5. Navigate to the `update_all.ps1` file in your repository, and update the `$Options` hashtable with the following + 5. Navigate to the `update_all.ps1` file in your repository, and update the `$Options` hashtable with the following ```powershell Gitter = @{ WebHookUrl = $env:gitter_webhook @@ -59,29 +59,29 @@ To set up plugin to create gist under your user name you need to give it your gi ``` 6. Enjoy your status updates, or frown on failures. -## [History](https://github.com/majkinetor/au/blob/master/AU/Plugins/History.ps1) +## [History](src/Plugins/History.ps1) -**Create update history as markdown report using git log**. +**Create update history as markdown report using git log**. Shows one date per line and all of the packages pushed to the Chocolatey community repository during that day. First letter of the package name links to report (produced by Report plugin), the rest links to actuall commit (produced by the Git plugin). This plugin requires Git plugin and that clone is done with adequate depth. -## [Mail](https://github.com/majkinetor/au/blob/master/AU/Plugins/Mail.ps1) +## [Mail](src/Plugins/Mail.ps1) **Send mail notifications on errors or always**. -* If you use Google mail for error notifications on a build server such as AppVeyor, Google may block authentication from unknown device. To receive those emails enable less secure apps - see [Allowing less secure apps to access your account](https://support.google.com/accounts/answer/6010255?hl=en). +* If you use Google mail for error notifications on a build server such as AppVeyor, Google may block authentication from unknown device. To receive those emails enable less secure apps - see [Allowing less secure apps to access your account](https://support.google.com/accounts/answer/6010255?hl=en). * If you do not want to use your private email for this, create a new Google account and redirect its messages to your private one. This wont affect you if you run the scripts from your own machine from which you usually access the email. -## [PullRequest](https://github.com/majkinetor/au/blob/master/AU/Plugins/PullRequest.ps1) +## [PullRequest](src/Plugins/PullRequest.ps1) **Create GitHub pull request for the updated packages**. The plugin will open a GitHub pull request for the commits created by the Git plugin, which of course needs to run first. It has options to add assignees and reviewers to the created pull request and, supports on-prem GitHub Enterprise Server. -## [Report](https://github.com/majkinetor/au/blob/master/AU/Plugins/Report.ps1) +## [Report](src/Plugins/Report.ps1) **Create different types of reports about the current run**. @@ -102,14 +102,14 @@ Report Types and associated Params: * *Title* - Title for the report. * *UserMessage* - Specify to add a message at the top of the report. -## [RunInfo](https://github.com/majkinetor/au/blob/master/AU/Plugins/RunInfo.ps1) +## [RunInfo](src/Plugins/RunInfo.ps1) **Save run info to the file and exclude sensitive information**. Run this plugin as the last one to save all other info produced during the run in such way that it can be recreated as object. To load it for inspection use `$info = Import-CliXml update_info.xml`. -## [Snippet](https://github.com/majkinetor/au/blob/master/AU/Plugins/Snippet.ps1) +## [Snippet](src/Plugins/Snippet.ps1) **Upload update history report to GitLab snippet**. @@ -118,4 +118,3 @@ To set up plugin to create snippet under your user name you need to give it your * Log into https://gitlab.com/users/sign_in with the user you want to use. * [Create a snippet](https://gitlab.com/snippets/new) (private or not) with a title and some random content. Grab the id at the end of it - `https://gitlab.com/snippets/{id}`. Set it as `$Env:snippet_id` environment variable. * Create [GitLab personal access token](https://gitlab.com/profile/personal_access_tokens) and **make sure token has _api_ scope selected**. Authenticating with username and password isn't supported for security reasons. Set it as `$Env:gitlab_api_token` environment variable. - diff --git a/README.md b/README.md index a7da60c9..d8a30095 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,11 @@ > NOTE: This PowerShell module is maintained by the Chocolatey Community as the original maintainer [archived the repository](https://github.com/majkinetor/au/commit/7f9c84e1e15995595dae68b4e8d8a71f50417752). To avoid confusion, and allow easier differentiation, this project has been named `chocolatey-au`. Chocolatey and the Chocolatey Community thanks [majkinetor](https://github.com/majkinetor) for their work on the module over the years. -> -> Please bear with us while we release the first build and update the documentation. In the meantime, there will continue to be reference to AU within the documentation. # Chocolatey Automatic Package Updater Module This PowerShell module implements functions that can be used to automate [Chocolatey](https://chocolatey.org) package updates. To learn more about Chocolatey automatic packages, please refer to the relevant [documentation](https://docs.chocolatey.org/en-us/create/automatic-packages). -To see AU in action see [video tutorial](https://www.youtube.com/watch?v=m2XpV2LxyEI&feature=youtu.be). +To see Chocolatey-AU in action see [video tutorial](https://www.youtube.com/watch?v=m2XpV2LxyEI&feature=youtu.be). ## Features @@ -16,7 +14,7 @@ To see AU in action see [video tutorial](https://www.youtube.com/watch?v=m2XpV2L - Automatically downloads installers and provides/verifies checksums for x32 and x64 versions. - Verifies URLs, nuspec versions, remote repository existence etc. - Automatically sets the nuspec descriptions from a README.md files. -- Update single package or any subset of previously created AU packages with a single command. +- Update single package or any subset of previously created Chocolatey-AU packages with a single command. - Multithread support when updating multiple packages. - Repeat or ignore specific failures when updating multiple packages. - Plugin system when updating everything, with few integrated plugins to send email notifications, save results to gist and push updated packages to git repository. @@ -27,21 +25,20 @@ To see AU in action see [video tutorial](https://www.youtube.com/watch?v=m2XpV2L ## Installation -AU module requires minimally PowerShell version 5: `$host.Version -ge '5.0'` +Chocolatey-AU module requires minimally PowerShell version 5: `$host.Version -ge '5.0'` To install it, use one of the following methods: -- PowerShell Gallery: [`Install-Module au`](https://www.powershellgallery.com/packages/AU). -- Chocolatey: [`choco install au`](https://chocolatey.org/packages/au). -- [Download](https://github.com/majkinetor/au/releases/latest) latest 7z package or latest build [artifact](https://ci.appveyor.com/project/majkinetor/au/build/artifacts). +- PowerShell Gallery: [`Install-Module chocolatey-au`](https://www.powershellgallery.com/packages/Chocolatey-AU). +- Chocolatey: [`choco install chocolatey-au`](https://chocolatey.org/packages/au). +- [Download](https://github.com/chocolatey-community/chocolatey-au/releases/latest) latest Chocolatey Package from GitHub. - -To quickly start using AU, fork [au-packages-template](https://github.com/majkinetor/au-packages-template) repository and rename it to `au-packages`. +To quickly start using Chocolatey-AU, fork [au-packages-template](https://github.com/majkinetor/au-packages-template) repository and rename it to `au-packages`. **NOTE**: All module functions work from within specific root folder. The folder contains all of your Chocolatey packages. ## Creating the package updater script -The AU uses `update.ps1` script that package maintainers should create in the package directory. No templates are used, just plain PowerShell. +The Chocolatey-AU uses `update.ps1` script that package maintainers should create in the package directory. No templates are used, just plain PowerShell. To write the package update script, it is generally required to implement 2 functions: `au_GetLatest` and `au_SearchReplace`. @@ -61,7 +58,7 @@ function global:au_GetLatest { } ``` -The returned version is later compared to the one in the nuspec file and if remote version is higher, the files will be updated. The returned keys of this HashTable are available via global variable `$global:Latest` (along with some keys that AU generates). You can put whatever data you need in the returned HashTable - this data can be used later in `au_SearchReplace`. +The returned version is later compared to the one in the nuspec file and if remote version is higher, the files will be updated. The returned keys of this HashTable are available via global variable `$global:Latest` (along with some keys that Chocolatey-AU generates). You can put whatever data you need in the returned HashTable - this data can be used later in `au_SearchReplace`. ### `au_SearchReplace` @@ -81,7 +78,7 @@ Function returns HashTable containing search and replace data for any package fi Search and replace strings are operands for PowerShell [replace](http://www.regular-expressions.info/powershell.html) operator. You do not have to write them most of the time however, they are rarely changed. -File paths are relative to the package directory. The function can use `$global:Latest` variable to get any type of information obtained when `au_GetLatest` was executed along with some AU generated data such as `PackageName`, `NuspecVersion` etc. +File paths are relative to the package directory. The function can use `$global:Latest` variable to get any type of information obtained when `au_GetLatest` was executed along with some Chocolatey-AU generated data such as `PackageName`, `NuspecVersion` etc. The following example illustrates the usage: @@ -96,13 +93,13 @@ function global:au_SearchReplace { } ``` -Here, line of the format `$url32 = ''` in the file `tools\chocolateyInstall.ps1` will have its quoted string replaced with latest URL (#1). The next line replaces value of the variable `$checksum32` on the start of the line with the latest checksum that is automatically injected in the `$Latest` variable by the AU framework (#2). Replacement of the latest version in the nuspec file is handled automatically. +Here, line of the format `$url32 = ''` in the file `tools\chocolateyInstall.ps1` will have its quoted string replaced with latest URL (#1). The next line replaces value of the variable `$checksum32` on the start of the line with the latest checksum that is automatically injected in the `$Latest` variable by the Chocolatey-AU framework (#2). Replacement of the latest version in the nuspec file is handled automatically. **NOTE**: The search and replace works on lines, multiple lines can not be matched with single regular expression. ### Update -With above functions implemented calling the `Update-Package` (alias `update`) function from the AU module will update the package when needed. +With above functions implemented calling the `Update-Package` (alias `update`) function from the Chocolatey-AU module will update the package when needed. You can then update the individual package by running the appropriate `update.ps1` script from within the package directory: @@ -173,7 +170,7 @@ The `update` function does the following checks: - The `$Latest.Version` will be checked to match a valid nuspec pattern. - Any hash key that starts with the word `Url`, will be checked for existence and MIME textual type, since binary is expected here. -- If the remote version is higher then the nuspec version, the Chocolatey site will be checked for existence of this package version (this works for unpublished packages too). This allows multiple users to update same set of packages without a conflict. Besides, this feature makes it possible not to persist state between the updates as once the package is updated and pushed, the next update will not push the package again. To persist the state of updated packages you can use for instance [Git](https://github.com/majkinetor/au/blob/master/AU/Plugins/Git.ps1) plugin which saves the updated and published packages to the git repository. +- If the remote version is higher then the nuspec version, the Chocolatey site will be checked for existence of this package version (this works for unpublished packages too). This allows multiple users to update same set of packages without a conflict. Besides, this feature makes it possible not to persist state between the updates as once the package is updated and pushed, the next update will not push the package again. To persist the state of updated packages you can use for instance [Git](Plugins/Git.ps1) plugin which saves the updated and published packages to the git repository. - The regex patterns in `au_SearchReplace` will be checked for existence. If any of the checks fails, package will not get updated. This feature releases you from the worries about how precise is your pattern match in both `au_` functions - if for example, a vendor site changes, the package update will fail because of the wrongly parsed data. @@ -188,8 +185,8 @@ For some packages, you may want to disable some of the checks by specifying addi ### Automatic checksums -**NOTE**: This feature works by invoking `chocolateyInstall.ps1` of the respective package with a [monkey-patched version of the `Get-ChocolateyWebFile` helper function](https://github.com/majkinetor/au/blob/a8d31244997f08685cc894da4faa1012c60b34f1/AU/Public/Update-Package.ps1#L172). The install script is supposed to either call this function explicitly or indirectly (e.g. `Install-ChocolateyInstallPackage $url`, which calls the former one). -In any case, upon execution of `Get-ChocolateyWebFile`, the install script will be **terminated**. Any actions in your script occurring after the call to `Get-ChocolateyWebFile` will **not** be run. This is due to the nature of [how the function gets monkey-patched](https://github.com/majkinetor/au/blob/a8d31244997f08685cc894da4faa1012c60b34f1/AU/Public/Update-Package.ps1#L172), which might be improved in the future. +**NOTE**: This feature works by invoking `chocolateyInstall.ps1` of the respective package with a [monkey-patched version of the `Get-ChocolateyWebFile` helper function](src/Public/Update-Package.ps1#L172). The install script is supposed to either call this function explicitly or indirectly (e.g. `Install-ChocolateyInstallPackage $url`, which calls the former one). +In any case, upon execution of `Get-ChocolateyWebFile`, the install script will be **terminated**. Any actions in your script occurring after the call to `Get-ChocolateyWebFile` will **not** be run. This is due to the nature of [how the function gets monkey-patched](src/Public/Update-Package.ps1#L172), which might be improved in the future. When new version is available, the `update` function will by default download both x32 and x64 versions of the installer and calculate the desired checksum. It will inject this info in the `$global:Latest` HashTable variable so you can use it via `au_SearchReplace` function to update hashes. The parameter `ChecksumFor` can contain words `all`, `none`, `32` or `64` to further control the behavior. @@ -205,7 +202,7 @@ If the checksum is actually obtained from the vendor's site, you can provide it return @{ ... Checksum32 = 'xxxxxxxx'; ChecksumType32 = 'md5'; ... } -If the `ChecksumXX` hash key is present, the AU will change to checksum verification mode - it will download the installer and verify that its checksum matches the one provided. If the key is not present, the AU will calculate hash with the given `ChecksumTypeXX` algorithm. +If the `ChecksumXX` hash key is present, the Chocolatey-AU will change to checksum verification mode - it will download the installer and verify that its checksum matches the one provided. If the key is not present, the Chocolatey-AU will calculate hash with the given `ChecksumTypeXX` algorithm. ### Manual checksums @@ -260,7 +257,7 @@ Points 2-4 do not apply if you set the explicit version using the variable `au_V - chocolatey _fix version_ always ends up in to the _Revision_ part of the package version; - existing _fix versions_ are changed to contain the current date; -- if _revision_ part is present in the package version and it is not in the _chocolatey fix notation_ form, AU will keep the existing version but notify about it; +- if _revision_ part is present in the package version and it is not in the _chocolatey fix notation_ form, Chocolatey-AU will keep the existing version but notify about it; Force can be triggered also from the `au_GetLatest` function. This may be needed if remote version doesn't change but there was nevertheless change on the vendor site. See the [example](https://github.com/majkinetor/au-packages/blob/master/cpu-z.install/update.ps1#L18-L39) on how to update the package when remote version is unchanged but hashsum of the installer changes. @@ -284,9 +281,9 @@ There is also a special variable `$au_GalleryPackageRootUrl` that can be added t > Note: The `$au_GalleryUrl` global variable also performs this function, but `$au_GalleryPackageRootUrl` allows more flexibility for internal and 3rd party package repositories. The `$au_GalleryUrl` will still work for compatibility, but makes assumptions about the URL that may not work in all situations. -### Reusing the AU updater with metapackages +### Reusing the Chocolatey-AU updater with metapackages -Metapackages can reuse an AU updater of its dependency by the following way: +Metapackages can reuse an Chocolatey-AU updater of its dependency by the following way: - In the dependent updater, instead of calling the `update` directly, use construct: @@ -296,7 +293,7 @@ Metapackages can reuse an AU updater of its dependency by the following way: - In the metapackage updater dot source the dependent updater and override `au_SearchReplace`. -This is best understood via example - take a look at the [cpu-z](https://github.com/majkinetor/au-packages/blob/master/cpu-z/update.ps1) AU updater which uses the updater from the [cpu-z.install](https://github.com/majkinetor/au-packages/blob/master/cpu-z.install/update.ps1) package on which it depends. It overrides the `au_SearchReplace` function and the `update` call but keeps the `au_GetLatest`. +This is best understood via example - take a look at the [cpu-z](https://github.com/majkinetor/au-packages/blob/master/cpu-z/update.ps1) Chocolatey-AU updater which uses the updater from the [cpu-z.install](https://github.com/majkinetor/au-packages/blob/master/cpu-z.install/update.ps1) package on which it depends. It overrides the `au_SearchReplace` function and the `update` call but keeps the `au_GetLatest`. ### Embedding binaries @@ -319,7 +316,7 @@ This function will also set the appropriate `$Latest.ChecksumXX`. ### Streams -The software vendor may maintain _multiple latest versions_, of specific releases because of the need for long time support. `au_GetLatest` provides an option to return multiple HashTables in order for its user to monitor each supported software _stream_. Prior to AU streams, each software stream was typically treated as a separate package and maintained independently. Using AU streams allows a single package updater to update multiple version streams in a single run: +The software vendor may maintain _multiple latest versions_, of specific releases because of the need for long time support. `au_GetLatest` provides an option to return multiple HashTables in order for its user to monitor each supported software _stream_. Prior to Chocolatey-AU streams, each software stream was typically treated as a separate package and maintained independently. Using Chocolatey-AU streams allows a single package updater to update multiple version streams in a single run: ```powershell function global:au_GetLatest { @@ -359,7 +356,7 @@ PS> $version.ToString(2) + ' => ' + $version.ToString() ### WhatIf -If you don't like the fact that AU changes the package inline, or just want to preview changes you can use `$WhatIf` parameter or `$au_WhatIf` global variable: +If you don't like the fact that Chocolatey-AU changes the package inline, or just want to preview changes you can use `$WhatIf` parameter or `$au_WhatIf` global variable: ```powershell PS C:\au-packages\copyq> $au_Force = $au_WhatIf = $true; .\update.ps1 @@ -372,7 +369,7 @@ WARNING: Package restored and updates saved to: C:\Users\majkinetor\AppData\Loca ``` **NOTES**: -- The inline editing is intentional design choice so that AU, its plugins and user scripts can use latest package data, such as latest version, checksum etc. +- The inline editing is intentional design choice so that Chocolatey-AU, its plugins and user scripts can use latest package data, such as latest version, checksum etc. - WhatIf can be used when updating all packages. - Since WhatIf saves the original package before the update and restores it after the update, interruption at specific time can cause package files to be left unrestored. In that case you can manually restore the package from `$Env:TEMP\au\\_backup` directory. This is in general not very likely however, because restore happens very quickly after the update. @@ -464,16 +461,16 @@ It is possible to specify a custom user logic in `Options` parameter - every key } ``` -The plugins above - `Report`, `Gist`,`Git`,`RunInfo` and `Mail` - are executed in the given order (hence the `[ordered]` flag) and AU passes them given options and saves the run results. +The plugins above - `Report`, `Gist`,`Git`,`RunInfo` and `Mail` - are executed in the given order (hence the `[ordered]` flag) and Chocolatey-AU passes them given options and saves the run results. -To add custom plugins, specify additional plugin search path via `$Options.PluginPath`. Plugin is a normal PowerShell script and apart from parameters given in its HashTable the AU will send it one more parameter `$Info` that contains current run info. The name of the script file must be the same as that of the key which value is used to pass the parameters to the plugin. If a key with the value of type `[HashTable]` doesn't point to existing PowerShell script it is not considered to be an AU plugin. +To add custom plugins, specify additional plugin search path via `$Options.PluginPath`. Plugin is a normal PowerShell script and apart from parameters given in its HashTable the Chocolatey-AU will send it one more parameter `$Info` that contains current run info. The name of the script file must be the same as that of the key which value is used to pass the parameters to the plugin. If a key with the value of type `[HashTable]` doesn't point to existing PowerShell script it is not considered to be a Chocolatey-AU plugin. To temporary disable plugins use `updateall` option `NoPlugins` or global variable `$au_NoPlugins`. -To temporary exclude the AU package from `updateall` procedure add `_` prefix to the package directory name. +To temporary exclude the Chocolatey-AU package from `updateall` procedure add `_` prefix to the package directory name. You can also execute a custom script via ScriptBlock specified via `BeforeEach` and `AfterEach` options. They will receive 2 parameters - package name and Options HashTable which you can use to pass any other parameter. -For more information take a look at the [plugins documentation](https://github.com/majkinetor/au/tree/master/Plugins.md). +For more information take a look at the [plugins documentation](Plugins.md). ### Make a script @@ -562,9 +559,9 @@ Returns the list of the packages which have `update.ps1` script in its directory ## Community - [Wormies AU Helpers](https://github.com/WormieCorp/Wormies-AU-Helpers) -Helper scripts to make maintaining packages using AU even easier -- [Chocolatey Core Community Maintainers Team Packages](https://github.com/chocolatey/chocolatey-coreteampackages) -The [largest](https://gist.github.com/choco-bot/a14b1e5bfaf70839b338eb1ab7f8226f) repository of AU packages by far +Helper scripts to make maintaining packages using Chocolatey-AU even easier +- [Chocolatey Community Chocolatey Packages](https://github.com/chocolatey-community/chocolatey-packages) +The [largest](https://gist.github.com/choco-bot/a14b1e5bfaf70839b338eb1ab7f8226f) repository of Chocolatey-AU packages by far ## Repository From 9e95e3b635e0ec0062fb68ed340101725d108ae5 Mon Sep 17 00:00:00 2001 From: Cory Knox Date: Mon, 6 May 2024 07:20:59 -0700 Subject: [PATCH 5/6] (maint) Update typo in the Plugins.md file --- Plugins.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Plugins.md b/Plugins.md index 21b0c748..0cd6803e 100644 --- a/Plugins.md +++ b/Plugins.md @@ -5,7 +5,7 @@ --- -[Chocolatey-AU plugins](Plugins) are [configured](README.md#plugins) using parameters passed in the HashTable contained in the Options under the key that is named by the plugin. So,`$Options.xyz=@{...}` is a plugin if `xyz.ps1` exists in a directory pointed to by the `PluginPath` updateall option. The Chocolatey-AU will then run this script and pass it `$Options.xyz` HashTable as plugin specific options. Chocolatey-AU comes with several integrated plugins that are described bellow. +[Chocolatey-AU plugins](Plugins) are [configured](README.md#plugins) using parameters passed in the HashTable contained in the Options under the key that is named by the plugin. So,`$Options.xyz=@{...}` is a plugin if `xyz.ps1` exists in a directory pointed to by the `PluginPath` updateall option. The Chocolatey-AU will then run this script and pass it `$Options.xyz` HashTable as plugin specific options. Chocolatey-AU comes with several integrated plugins that are described below. Default [update_all.ps1](https://github.com/majkinetor/au-packages-template/blob/master/update_all.ps1) uses environment variables to configure some options. If you use [AppVeyor](https://github.com/majkinetor/au/wiki/AppVeyor) set those variables in the [.appveyor.yml](https://github.com/majkinetor/au-packages-template/blob/master/.appveyor.yml) and to run it locally use [update_vars.ps1](https://github.com/majkinetor/au-packages-template/blob/master/update_vars_default.ps1). @@ -24,7 +24,7 @@ To set up plugin to create gist under your user name you need to give it your gi **Persist modified files**. -* To use it locally, just ensure `git push` doesn't require credentials and dont set any environment variables. +* To use it locally, just ensure `git push` doesn't require credentials and don't set any environment variables. * To use on build server such as [[AppVeyor]], specify `$Env:username` and `$Env:password`. If you host git repository on Github its preferable to use personal access token. You can use the same token as with gist as long as _**public repo**_ scope is activated. ## [GitLab](src/Plugins/GitLab.ps1) From 399292cb05b8b11b39ce112a69373801bdbff181 Mon Sep 17 00:00:00 2001 From: Cory Knox Date: Mon, 6 May 2024 07:21:07 -0700 Subject: [PATCH 6/6] Apply suggestions from code review --- Migrating-AU-to-Chocolatey-AU.md | 1 - 1 file changed, 1 deletion(-) diff --git a/Migrating-AU-to-Chocolatey-AU.md b/Migrating-AU-to-Chocolatey-AU.md index a0347b49..8f99fcad 100644 --- a/Migrating-AU-to-Chocolatey-AU.md +++ b/Migrating-AU-to-Chocolatey-AU.md @@ -8,7 +8,6 @@ How you migrate from `AU` to `Chocolatey-AU` will depend on how you used `AU` in If you are cloning the [original `AU` repository](https://github.com/majkinetor/au/) and building the module from there, you will want to update to clone the Chocolatey Community `Chocolatey-AU` repository: `https://github.com/chocolatey-community/chocolatey-au.git` instead. Once that has been done, you will want to [amend your update scripts](#amending-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`. - ## Your Repository Installs AU From the Chocolatey Community Repository If you are installing `AU` from the [Chocolatey Community Repository](https://community.chocolatey.org/), you will want to update it to `choco install chocolatey-au --confirm` instead of `choco install au -y`. Once that has been done, you will want to [update your update scripts](#amending-your-update-scripts) to use the `Chocolatey-AU` PowerShell Module instead of `AU`.