Echo Generator

Generator/generator-botbuilder-java/LICENSE → Generator/generator-botbuilder-java/LICENSE.md

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2018 Microsoft 
+Copyright (c) 2018 Microsoft Corporation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ 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 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.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Generator/generator-botbuilder-java/README.md

@@ -1,38 +1,120 @@
-# generator-botbuilder-java [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage percentage][coveralls-image]][coveralls-url]
-> Template to create conversational bots in Java using Microsoft Bot Framework.
+# generator-botbuilder-java
+
+Yeoman generator for [Bot Framework v4](https://dev.botframework.com).  Will let you quickly set up a conversational AI bot
+using core AI capabilities.
+
+## About
+
+`generator-botbuilder-java` will help you build new conversational AI bots using the [Bot Framework v4](https://dev.botframework.com).
+
+## Templates
+
+The generator supports three different template options.  The table below can help guide which template is right for you.
+
+|  Template  |  Description  |
+| ---------- |  ---------  |
+| Echo Bot | A good template if you want a little more than "Hello World!", but not much more.  This template handles the very basics of sending messages to a bot, and having the bot process the messages by repeating them back to the user.  This template produces a bot that simply "echoes" back to the user anything the user says to the bot. |
+| Empty Bot | A good template if you are familiar with Bot Framework v4, and simply want a basic skeleton project.  Also a good option if you want to take sample code from the documentation and paste it into a minimal bot in order to learn. |
+
+### How to Choose a Template
+
+| Template | When This Template is a Good Choice |
+| -------- | -------- |
+| Echo Bot  | You are new to Bot Framework v4 and want a working bot with minimal features. |
+| Empty Bot  | You are a seasoned Bot Framework v4 developer.  You've built bots before, and want the minimum skeleton of a bot. |
+
+### Template Overview
+
+#### Echo Bot Template
+
+The Echo Bot template is slightly more than the a classic "Hello World!" example, but not by much.  This template shows the basic structure of a bot, how a bot recieves messages from a user, and how a bot sends messages to a user.  The bot will "echo" back to the user, what the user says to the bot.  It is a good choice for first time, new to Bot Framework v4 developers.
+
+#### Empty Bot Template
+
+The Empty Bot template is the minimal skeleton code for a bot.  It provides a stub `onTurn` handler but does not perform any actions.  If you are experienced writing bots with Bot Framework v4 and want the minimum scaffolding, the Empty template is for you.
 
 ## Installation
 
-First, install [Yeoman](http://yeoman.io) and generator-botbuilder-java using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)).
+1. Install [Yeoman](http://yeoman.io) using [npm](https://www.npmjs.com) (we assume you have pre-installed [node.js](https://nodejs.org/)).
+
+    ```bash
+    # Make sure both are installed globally
+    npm install -g yo
+    ```
+
+2. Install generator-botbuilder-java by typing the following in your console:
+
+    ```bash
+    # Make sure both are installed globally
+    npm install -g generator-botbuilder-java
+    ```
+
+3. Verify that Yeoman and generator-botbuilder-java have been installed correctly by typing the following into your console:
+
+    ```bash
+    yo botbuilder-java --help
+    ```
+
+## Usage
+
+### Creating a New Bot Project
+
+When the generator is launched, it will prompt for the information required to create a new bot.
 
 ```bash
-npm install -g yo
-npm install -g generator-botbuilder-java
+# Run the generator in interactive mode
+yo botbuilder-java
 ```
 
-Then generate your new project:
+### Generator Command Line Options
+
+The generator supports a number of command line options that can be used to change the generator's default options or to pre-seed a prompt.
+
+| Command line Option  | Description |
+| ------------------- | ----------- |
+| --help, -h        | List help text for all supported command-line options |
+| --botName, -N     | The name given to the bot project |
+| --packageName, -P | The Java package name to use for the bot |
+| --template, -T    | The template used to generate the project.  Options are `empty`, or `echo`.  See [https://aka.ms/botbuilder-generator](https://aka.ms/botbuilder-generator) for additional information regarding the different template option and their functional differences. |
+| --noprompt        | The generator will not prompt for confirmation before creating a new bot.  Any requirement options not passed on the command line will use a reasonable default value.  This option is intended to enable automated bot generation for testing purposes. |
+
+#### Example Using Command Line Options
+
+This example shows how to pass command line options to the generator, setting the default language to TypeScript and the default template to Core.
 
 ```bash
-yo botbuilder-java
+# Run the generator defaulting the pacakge name and the template
+yo botbuilder-java --P "com.mycompany.bot" --T "echo"
 ```
 
-## Getting To Know Yeoman
+### Generating a Bot Using --noprompt
 
- * Yeoman has a heart of gold.
- * Yeoman is a person with feelings and opinions, but is very easy to work with.
- * Yeoman can be too opinionated at times but is easily convinced not to be.
- * Feel free to [learn more about Yeoman](http://yeoman.io/).
+The generator can be run in `--noprompt` mode, which can be used for automated bot creation.  When run in `--noprompt` mode, the generator can be configured using command line options as documented above.  If a command line option is ommitted a reasonable default will be used.  In addition, passing the `--noprompt` option will cause the generator to create a new bot project without prompting for confirmation before generating the bot.
 
-## License
+#### Default Options
 
-MIT © [Microsoft]()
+| Command line Option  | Default Value |
+| ------------------- | ----------- |
+| --botname, -N     | `echo` |
+| --packageName, -p | `echo` |
+| --template, -T    | `echo` |
+
+#### Examples Using --noprompt
+
+This example shows how to run the generator in --noprompt mode, setting all required options on the command line.
+
+```bash
+# Run the generator, setting all command line options
+yo botbuilder-java --noprompt -N "MyEchoBot" -P "com.mycompany.bot.echo" -T "echo"
+```
+
+This example shows how to run the generator in --noprompt mode, using all the default command line options.  The generator will create a bot project using all the default values specified in the **Default Options** table above.
+
+```bash
+# Run the generator using all default options
+yo botbuilder-java --noprompt
+```
 
+## Logging Issues and Providing Feedback
 
-[npm-image]: https://badge.fury.io/js/generator-botbuilder-java.svg
-[npm-url]: https://npmjs.org/package/generator-botbuilder-java
-[travis-image]: https://travis-ci.org/Microsoft/generator-botbuilder-java.svg?branch=master
-[travis-url]: https://travis-ci.org/Microsoft/generator-botbuilder-java
-[daviddm-image]: https://david-dm.org/Microsoft/generator-botbuilder-java.svg?theme=shields.io
-[daviddm-url]: https://david-dm.org/Microsoft/generator-botbuilder-java
-[coveralls-image]: https://coveralls.io/repos/Microsoft/generator-botbuilder-java/badge.svg
-[coveralls-url]: https://coveralls.io/r/Microsoft/generator-botbuilder-java
+Issues and feedback about the botbuilder generator can be submitted through the project's [GitHub Issues](https://github.com/Microsoft/botbuilder-samples/issues) page.