Merge pull request #50 from corbob/49-add-a-migration-guide-type-docu…

…ment

(#49) Add migration page

Migrating-AU-to-Chocolatey-AU.md

@@ -0,0 +1,21 @@
+# Migrating From `AU` To `Chocolatey-AU`
+
+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, 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
+
+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`.
+
+## Your Repository Installs AU From the Powershell Gallery
+
+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`.
+
+## 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.

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 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).
 
-## [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 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](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,37 +51,37 @@ 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
      }
      ```
   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.
-