(doc) update readme files

Provide more information in the readme files

README.md

@@ -2,8 +2,11 @@
 
 This contains Chocolatey packages, both manually and automatically maintained.
 
+You can choose to use one or both of the different methods currently supported in the Chocolatey community for automatic packaging. They are AU (Automatic Updater) and Ketarin/ChocolateyPackageUpdater.
+
 ### Folder Structure
 
+* au - The scripts for running Automatic Updater (AU) are here.
 * automatic - where automatic packaging and packages are kept. These are packages that are automatically maintained using either [AU](https://chocolatey.org/packages/au) or [Ketarin](https://chocolatey.org/packages/ketarin)/[ChocolateyPackageUpdater](https://chocolatey.org/packages/chocolateypackageupdater) combo.
 * icons - Where you keep icon files for the packages. This is done to reduce issues when packages themselves move around.
 * ketarin - where ketarin jobs (aka applications or searches) exported as XML are kept. This is done to allow ease of contribution.
@@ -13,6 +16,33 @@ This contains Chocolatey packages, both manually and automatically maintained.
 
 For setting up your own automatic package repository, please see [Automatic Packaging](https://chocolatey.org/docs/automatic-packages)
 
+### Requirements
+
+* Chocolatey (choco.exe)
+
+#### Ketarin / ChocolateyPackageUpdater
+
+* PowerShell v2+
+* [Ketarin](https://chocolatey.org/packages/ketarin)
+* [Chocolatey Package Updater](https://chocolatey.org/packages/chocolateypackageupdater)
+* A Windows box somewhere - to run the updater on - appveyor can't work until the import of the settings can be automated
+
+#### AU
+
+* PowerShell v3+.
+* The [AU module](https://chocolatey.org/packages/au).
+* Ruby (and the gist gem) for publishing GitHub Gists.
+
+### Getting started
+
+1. Head into the `setup` folder and perform the proper steps for your choice of setup.
+
+### Recommendation on Auto Packaging
+
+AU may have a few more setup steps, but it provides more in the process of being completely automated, sending emails when things go wrong, and providing a nice report at the end. It doesn't have a bolt-on feeling to it that you see with Ketarin / ChocolateyPackageUdater, however the one thing it does lack in comparison is no visual feedback to seeing how searches for installers may be found. Other than that, it provides errors when things go wrong, where Ketarin doesn't consider anything that happens during "before run"/"post run updates" (where chocopkgup and checksumming occur) to be an error, even if those scripts error.
+
+So for best visibility, enjoying the ease of using AppVeyor, and for a nice report of results, we recommend AU over Ketarin. You also don't need to deal with templates as AU works directly with the xml/ps1 files to do replacement.
+
 ### Special Notes
 
 #### Ketarin

automatic/README.md

@@ -11,6 +11,14 @@ The following packages implement this strategy of auto updates:
 * 1password
 * git.install
 
+There is also an _output folder where the automatic packaging files with tokens to do token replacment and output package files with actual values in this folder. This folder is necessary for chocopkgup to do its work. You can decide whether to commit this set of folders or not. We recommend committing it as it makes it easier to do one off fixes and contributors to submit fixes for a package.
+
 ### Automatic Updater (AU)
 
-TBD
+AU works with packages without automatic package tokens necessary. So you can treat the packages as normal.
+
+**NOTE:** Ensure when you are creating packages for AU, you don't use `--auto` as the packaging files should be normal packages. AU doesn't need the tokens to do replacement.
+
+The following packages implement this strategy of auto updates:
+
+* TBD

ops/README.md

@@ -6,4 +6,4 @@
 
 ### AutomaticUpdater
 
-Nothing to do here, jobs run automatically by AppVeyor on commit.
+Nothing to do here, jobs run automatically by AppVeyor on commit and on a schedule that you've set up in AppVeyor.

setup/README.md

@@ -1,17 +1,25 @@
-## Setup
+# Setup
 
-### Ketarin/ChocolateyPackageUpdater Automatic Packaging
+## Ketarin / ChocolateyPackageUpdater Automatic Packaging
 
 * Review `ketarin_setup.ps1` to ensure all items are set appropriately. Uncomment/change anything you need to now.
 * Run `ketarin_setup.ps1`
 * Open ketarin after installing it, open the settings and import `KetarinSettings.xml`.
+* Set up push for Chocolatey community feed with your API key.
+* Ensure `git push` doesn't require credentials.
+* Review `ops/ketarinupdate.cmd` to ensure it is good to go.
 
-### Automatic Updater (AU)
+**Note**: Use `ops/ketarinupdate.cmd` or similar to schedule updates.
+
+## Automatic Updater (AU)
 
 * Review `au_setup.ps1` to ensure all items are set appropriately. Uncomment/change anything you need to now.
-* Run `au_setup.ps1`
+* Run `au_setup.ps1`.
+* Log into https://gist.github.com with the user you want to use to perform commits and pushes to git.
+* Create an empty gist (secret or not). Grab the id at the end of it - `https://gist.github.com/name/{id}`. You will need that for `appveyor.yml` and `update_vars.ps1`.
+* Now we need to set up AppVeyor and our local runs.
 
-#### Set up AppVeyor for packaging
+### Set up AppVeyor for packaging
 * Go to AppVeyor and sign up/sign in. https://ci.appveyor.com/
 * Set up an appveyor job - https://ci.appveyor.com/projects/new
 * Select your repository to create a new job.
@@ -22,17 +30,20 @@
   * Click Save.
 
 * Get encrypted values for - https://ci.appveyor.com/tools/encrypt (requires login first)
-   * github password (or auth token for 2FA)
-   * email password
-   * Chocolatey API key
+  * github password (or auth token for 2FA)
+  * email password
+  * Chocolatey API key
 * Edit the appveyor.yml to add those values in.
 * Edit the appveyor.yml with the other configuration related items.
 
-#### Setup Local Runs
+### Setup Local Runs
 * Edit `au/update_vars.ps1` and set the same variables there.
-* You may also want to install `gist` gem: `cinst ruby; gem install gist` and to make sure `git push` doesn't require credentials.
+* As part of setup, you ensured that you have the Ruby gem `gist` installed. Please run `gist --login` to provide your credentials
+* Ensure `git push` doesn't require credentials.
+
+**Note**: You can also set up a scheduled task for local runs.
 
-#### Notes
+### AU Notes
 
 * 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). In any case, do not use your private email for this but 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.
 * If you are using AppVeyor you should schedule your build under the _General_ options using [Cron](http://www.nncron.ru/help/EN/working/cron-format.htm) syntax, for example `0 22 * * * *` runs the updater every night at 22h. `5 * * * * *` runs the updater every hour at five past the hour.