Merge pull request #57 from loadsys/f/docs-update

F/docs update

Author: beporter

LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright (c) 2015 Loadsys Web Strategies
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+> THE SOFTWARE.

README.md

@@ -1,12 +1,11 @@
 # Loadsys Cake Command Line Scripts
 
-**DISCLAIMER: We use these tools ourselves, but that doesn't mean they will necessarily work for you in your situation. This repo is public in case it can be of use to anyone else (and because it's convenient for us), but it _is not supported_ and _may change without notice_. Issues and contributions may be flat out ignored if they don't impact us. You have been warned!**
+This collection of scripts is intended to provide consistency and shortcuts for common project tasks. Key tools are highlighted and described below. Coordinates heavily with the [Loadsys CakePHP App Skeleton](https://github.com/loadsys/CakePHP-Skeleton).
+
+* This is the `master` branch and along with the `3.x.x` releases is meant for use with Cake 3 projects exclusively.
+* The [`cake-2.x`](https://github.com/loadsys/CakePHP-Shell-Scripts/tree/cake-2.x) branch and `2.x.x` releases are meant for Cake 2.x projects that use composer (git submodules are still supported).
 
-This collection of scripts is intended to provide consistency and shortcuts for common project tasks. Key tools are highlighted and described below.
 
-* The master branch is meant for use with Cake 3 projects exclusively.
-* The 2.x branch is meant for Cake 2.x projects that use composer (git submodules are still supported).
-* The 1.x branch is tuned for Cake 1.x projects that use git submodules for dependency management.
 * Most scripts listed below can take a `-h` option as their first argument to output usage information.
 * Most are designed to run with few or no arguments; they try to guess sensible defaults whenever possible.
 * Most are designed to fail gracefully with a non-zero exit code.
@@ -20,8 +19,9 @@ The following dependencies are assumed to be available on the target system and
 * `composer`
 * `git`
 * `mail`
+* `mysql`
 * `mysqldump`
-* `php`
+* `php` (v5.6 recommended)
 * `realpath` (not available by default on OS X)
 * `readlink`
 * `zip`
@@ -52,9 +52,10 @@ Your project's `composer.json` file should include something like this:
 	}
 }
 ```
+
 Then run `composer install` to pull this repo into your project. A `bin/` folder should be created in your project root with symlinks to all of the scripts from this package.
 
-**Note**: The `bin-dir` is non-standard and may cause conflicts with other composer packages that install "binaries". These scripts are all expect to live in `PROJECT_ROOT/bin` though so don't expect anything to work if you forgo the `bin-dir` setting in your project.
+**Note**: The `bin-dir` is non-standard and may cause conflicts with other composer packages that install "binaries". The bundled scripts all expect to live in `PROJECT_ROOT/bin` though so don't expect anything to work if you forgo the `bin-dir` setting in your project.
 
 
 ## Contributing Improvements
@@ -73,42 +74,69 @@ There currently is not a convenient way to set up a test harness around this rep
 ## Notable Scripts
 
 
-### bin/update
+### bin/cache-clear
+
+Uses the new `ConsoleShell` to iterate over all of the configured Caches in your app and clear each one.
+
+
+### bin/codesniffer-run
+
+Wraps the call to PHPCodeSniffer so that it can be called from inside or outside a Vagrant VM. Also checks the `installed_paths` configuration of phpcs and injects the necessary paths for the CakePHP and Loadsys coding standards if they are not already present.
+
+
+### bin/coverage-ensure
+
+Reads the location of the `clover.xml` file generated from your phpunit runs from your `phpunit.xml[.dist]` file, then examines that file for how much of your code is covered. Takes an integer command line argument representing the minimum required percentage, and returns with an exit status non-zero if your coverage is lacking. Intended for use during automated testing runs, such as on Travis.
+
+
+### bin/db-backup
+
+Uses the default database credentials in `config/app.php` to create a ZIPed `mysqldump` of that database in a local `backups/` folder. Helpful because you don't have to specify DB credentials. It also reports the ZIP size to help you keep a mental tally over time.
+
+Can be used manually for one-off backups before dangerous operations (such as a code deploy and DB migrations), or automatically (such as in a Vagrant VM shutdown script, to preserve an internal DB and protect it from `vagrant destroy`.)
+
+
+### bin/db-login
+
+A simple shortcut script that uses the `[Datasources][default]` key defined in `config/app.php` to start a command line `mysql` session for you. Incredibly convenient in a production environment to run manual data queries during troubleshooting.
+
+Also properly handles I/O redirection, so any time you would normally run `mysql --user=user -ppass --host=host --port=3306 database_name < import.sql` you can instead just run `bin/db-login < import.sql` and never have to worry about the connection credentials. Great for scripting and provisioning.
+
+
+### bin/deploy
 
 Automates all of the steps for a read-only copy of the app (such as staging or production) to pull new code from the repo and update the local running copy. It performs tasks like:
 
 * Checking the local working copy to make sure no changes have been made from the checked-out commit that might prevent an automatic pull or merge.
 * Backing up the active database (crudely, but effective for smallish apps).
-* On older projects, checking for db_updates.sql changes that should be applied before merging new code and pausing to display them to the user before proceeding.
 * Pulling and merging code from the remote repo.
 * Applying Migrations, if present.
 * Clearing Cake cache directories.
 * Copying over environment-specific configs, if present.
-* Updating git submodules.
+* Updating git submodules and/or composer dependencies.
 * Ensuring file ownership and write permissions are still correct.
-* Showing the user the new active commit's log.
+* Showing the user the new active commit's log and optionally generating a notification email.
 
 
-### bin/db-login
+### bin/docs-generate
 
-A simple shortcut script that uses the `[Datasources][default]` key defined in `config/app.php` to start a command line `mysql` session for you. Incredibly convenient in a production environment to run manual data queries during troubleshooting.
+Wraps the call to phpDocumentor so that it can be called from inside or outside a Vagrant VM but always executed inside.
 
 
-### bin/db-backup
+### bin/tests-run
 
-Uses the default database credentials in `config/app.php` to create a ZIPed `mysqldump` of that database in a local `backups/` folder. Helpful because you don't have to specify DB credentials. It also reports the ZIP size to help you keep a mental tally over time.
+Intended to serve as a convenience method for executing phpunit since it's callable from your host machine and will execute tests inside of vagrant in that case.
 
-
-### @TODO:
-
-Add cache-clear, tests-run, docs-generate, codesniffer-run here as notable scripts.
+It can also take a partial filename as an argument and run the corresponding test case directly. This mode of use is intended to be paired with a file watcher, like [kicker](https://github.com/alloy/kicker), [grunt](http://gruntjs.com/) or [efsw](https://bitbucket.org/SpartanJ/efsw). When a source file or its test case counterpart is changed, the tests for that single file can be executed automatically inside the VM.
 
 
 ## License
 
-MIT
+[MIT](LICENSE.md)
+
+**DISCLAIMER: We use these tools ourselves, but that doesn't mean they will necessarily work for you in your situation. This repo is public in case it can be of use to anyone else (and because it's convenient for us), but it _is not supported_ and _may change without notice_. Issues and contributions may be ignored if they don't impact us. You have been warned!**
 
 
 ## Copyright
 
-Copyright 2015 Loadsys Web Strategies
+Copyright &copy; 2015 [Loadsys Web Strategies](http://loadsys.com)