Changes to make our project as welcoming as possible for new contributors.

Changes include:
1) Added CONTRIBUTING.md with detailed instructions for how to contribute, which should be especially useful to those new to open source in general or GitHub in particular
2) Added CODE_OF_CONDUCT.md which sets ground rules for participants’ behavior and helps to facilitate a friendly, welcoming environment
3) Renamed the "example" directory to "examples" in the hope that one day soon there may be more than a single example ;-)

10 files changed, 546 insertions, 4 deletions

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 00000000..04772fc8
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,74 @@
+# cmd2 Contributor Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at federico.ceratto at gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..52c7baea
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,468 @@
+# Contributor's Guide
+
+We welcome pull requests from cmd2 users and seasoned Python developers alike! Follow these steps to contribute:
+
+1. Find an issue that needs assistance by searching for the [Help Wanted](https://github.com/python-cmd2/cmd2/labels/help%20wanted) tag.
+
+2. Let us know you are working on it by posting a comment on the issue.
+
+3. Follow the [Contribution Guidelines](#contribution-guidelines) to start working on the issue.
+
+Remember to feel free to ask for help by leaving a comment within the Issue.
+
+Working on your first Pull Request? You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github).
+
+###### If you've found a bug that is not on the board, [follow these steps](#found-a-bug).
+
+--------------------------------------------------------------------------------
+
+## Contribution Guidelines
+
+- [Prerequisites](#prerequisites)
+- [Forking The Project](#forking-the-project)
+- [Create A Branch](#create-a-branch)
+- [Setup Linting](#setup-linting)
+- [Setup for cmd2 development](#setup-for-cmd2-development)
+- [Make Changes](#make-changes)
+- [Run The Test Suite](#run-the-test-suite)
+- [Squash Your Commits](#squash-your-commits)
+- [Creating A Pull Request](#creating-a-pull-request)
+- [Common Steps](#common-steps)
+- [How We Review and Merge Pull Requests](#how-we-review-and-merge-pull-requests)
+- [How We Close Stale Issues](#how-we-close-stale-issues)
+- [Next Steps](#next-steps)
+- [Other resources](#other-resources)
+- [Advice](#advice)
+
+### Prerequisites
+
+The tables below list all prerequisites along with the minimum required version for each.
+
+> _Updating to the latest releases for all prerequisites via pip or conda is recommended_.
+
+#### Prerequisites to run cmd2 applications
+
+| Prerequisite                                | Minimum Version |
+| ------------------------------------------- | --------------- |
+| [Python](https://www.python.org/downloads/) | `3.3 or 2.7`    |
+| [six](https://pypi.python.org/pypi/six)     | `1.8`           |
+| [pyparsing](http://pyparsing.wikispaces.com)| `2.0.3`         |
+
+#### Additional prerequisites to run cmd2 unit tests
+
+| Prerequisite                                | Minimum Version |
+| ------------------------------------------- | --------------- |
+| [pytest](http://doc.pytest.org/en/latest/)  | `2.6.3`         |
+| [mock](https://pypi.python.org/pypi/six)    | `1.0.1`         |
+
+### Additional prerequisites to build cmd2 documentation
+| Prerequisite                                | Minimum Version |
+| ------------------------------------------- | --------------- |
+| [sphinx](http://www.sphinx-doc.org)         | `1.2.3`         |
+| [sphinx-rtd-theme](https://github.com/snide/sphinx_rtd_theme) | `0.1.6` |
+
+### Optional prerequisites for enhanced unit test features
+| Prerequisite                                | Minimum Version |
+| ------------------------------------------- | --------------- |
+| [pytest-xdist](https://pypi.python.org/pypi/pytest-xdist)| `1.15` |
+| [pytest-cov](https://pypi.python.org/pypi/pytest-cov) | `1.8` |
+
+If Python is already installed in your machine, run the following commands to validate the versions:
+
+```shell
+python -V
+pip freeze | grep six
+pip freeze | grep pyparsing
+```
+
+If your versions are lower than the prerequisite versions, you should update.
+
+If you do not already have Python installed on your machine, we recommend using the [Anaconda](https://www.continuum.io/downloads) distribution because it provides an excellent out-of-the-box install on all Platforms (Windows, Mac, or Linux) and because it supports having multiple Python environments (versions of Python) installed simultaneously.
+
+### Forking The Project
+
+#### Setting Up Your System
+
+1. Install [Git](https://git-scm.com/) or your favorite Git client.  If you aren't comfortable with Git at the command-line, then both [SmartGit](http://www.syntevo.com/smartgit/) and [GitKraken](https://www.gitkraken.com) are excellent cross-platform graphical Git clients.
+2. (Optional) [Setup an SSH Key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub.
+3. Create a parent projects directory on your system. For this guide, it will be assumed that it is `~/src`
+
+#### Forking cmd2
+
+1. Go to the top level cmd2 repository: <https://github.com/python-cmd2/cmd2>
+2. Click the "Fork" Button in the upper right hand corner of the interface ([More Details Here](https://help.github.com/articles/fork-a-repo/))
+3. After the repository has been forked, you will be taken to your copy of the cmd2 repo at `yourUsername/cmd2`
+
+#### Cloning Your Fork
+
+1. Open a Terminal / Command Line / Bash Shell in your projects directory (_i.e.: `/yourprojectdirectory/`_)
+2. Clone your fork of cmd2
+
+```shell
+$ git clone https://github.com/yourUsername/cmd2.git
+```
+
+##### (make sure to replace `yourUsername` with your GitHub Username)
+
+This will download the entire cmd2 repo to your projects directory.
+
+#### Setup Your Upstream
+
+1. Change directory to the new cmd2 directory (`cd cmd2`)
+2. Add a remote to the official cmd2 repo:
+
+```shell
+$ git remote add upstream https://github.com/python-cmd2/cmd2.git
+```
+
+Congratulations, you now have a local copy of the cmd2 repo!
+
+#### Maintaining Your Fork
+
+Now that you have a copy of your fork, there is work you will need to do to keep it current.
+
+##### **Rebasing from Upstream**
+
+Do this prior to every time you create a branch for a PR:
+
+1. Make sure you are on the `master` branch
+
+  > ```shell
+  > $ git status
+  > On branch master
+  > Your branch is up-to-date with 'origin/master'.
+  > ```
+
+  > If your aren't on `master`, resolve outstanding files / commits and checkout the `master` branch
+
+  > ```shell
+  > $ git checkout master
+  > ```
+
+2. Do A Pull with Rebase Against `upstream`
+
+  > ```shell
+  > $ git pull --rebase upstream master
+  > ```
+
+  > This will pull down all of the changes to the official master branch, without making an additional commit in your local repo.
+
+3. (_Optional_) Force push your updated master branch to your GitHub fork
+
+  > ```shell
+  > $ git push origin master --force
+  > ```
+
+  > This will overwrite the master branch of your fork.
+
+### Create A Branch
+
+Before you start working, you will need to create a separate branch specific to the issue / feature you're working on. You will push your work to this branch.
+
+#### Naming Your Branch
+
+Name the branch something like `fix/xxx` or `feature/xxx` where `xxx` is a short description of the changes or feature you are attempting to add. For example `fix/script-files` would be a branch where you fix something specific to script files.
+
+#### Adding Your Branch
+
+To create a branch on your local machine (and switch to this branch):
+
+```shell
+$ git checkout -b [name_of_your_new_branch]
+```
+
+and to push to GitHub:
+
+```shell
+$ git push origin [name_of_your_new_branch]
+```
+
+##### If you need more help with branching, take a look at _[this](https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches)_.
+
+### Setup Linting
+
+You should have some sort of [PEP8](https://www.python.org/dev/peps/pep-0008/)-based linting running in your editor or IDE or at the command-line before you commit code.  [pylint](https://www.pylint.org) is a good Python linter which can be run at the command-line but also can integrate with many IDEs and editors.
+
+> Please do not ignore any linting errors in code you write or modify, as they are meant to **help** you and to ensure a clean and simple code base.  Don't worry about linting errors in code you don't touch though - cleaning up the legacy code is a work in progress.
+
+
+### Setup for cmd2 development
+Once you have cmd2 cloned, before you start any cmd2 application, you first need to install all of the dependencies:
+
+```bash
+# Install cmd2 prerequisites
+pip install -U six pyparsing
+
+# Install prerequisites for running cmd2 unit tests
+pip install -U pytest mock
+
+# Install prerequisites for building cmd2 documentation
+pip install -U sphinx sphinx-rtd-theme
+
+# Install optional prerequisites for running unit tests in parallel and doing code coverage analysis
+pip install -U pytest-xdist pytest-cov
+```
+
+For doing cmd2 development, you actually do NOT want to have cmd2 installed as a Python package.  
+So if you have previously installed cmd2, make sure to uninstall it:
+```bash
+pip uninstall cmd2
+```
+
+Then you should modify your PYTHONPATH environment variable to include the directory you have cloned the cmd2 repository to.
+Add a line similar to the following to your .bashrc, .bashprofile, or to your Windows environment variables:
+
+```bash
+# Use cmd2 Python module from GitHub clone when it isn't installed
+export PYTHONPATH=$PYTHONPATH:~/src/cmd2
+```
+
+Where `~src/cmd2` is replaced by the directory you cloned your fork of the cmd2 repo to.
+
+Now navigate to your terminal to the directory you cloned your fork of the cmd2 repo to and
+try running the example to make sure everything is working:
+
+```bash
+cd ~src/cmd2
+python examples/example.py
+```
+
+If the example app loads, you should see a prompt that says "(Cmd)".  You can type `help` to get help or `quit` to quit.
+If you see that, then congratulations – you're all set. Otherwise, refer to the cmd2 [Installation Instructions](https://cmd2.readthedocs.io/en/latest/install.html#installing).  There also might be an error in the console
+of  your Bash / Terminal / Command Line that will help identify the problem.
+
+### Make Changes
+This bit is up to you!
+
+#### How to find the code in the cmd2 codebase to fix/edit?
+
+The cmd2 project directory structure is pretty simple and straightforward.  All actual code for cmd2
+is located in a single file, `cmd2.py`.  The code to generate the documentation is in the `docs` directory.  Unit tests are in the `tests` directory.  The `examples` directory contains examples of how
+to use cmd2.  There are various other files in the root directory, but these are primarily related to
+continuous integration and to release deployment.
+
+#### Changes to the documentation files
+If you made changes to any file in the `/docs` directory, you need to build the Sphinx documentation
+and make sure your changes look good:
+```shell
+cd docs
+make clean html
+```
+In order to see the changes, use your web browser of choice to open `<cmd2>/docs/_build/html/index.html`.
+
+### Run The Test Suite
+When you're ready to share your code, run the test suite:
+
+```shell
+cd <cmd2>
+py.test
+```
+
+and ensure all tests pass.
+
+If you have the `pytest-xdist` pytest distributed testing plugin installed, then you can use it to
+dramatically speed up test execution by running tests in parallel on multiple cores like so:
+
+```shell
+py.test -n4
+```
+where `4` should be replaced by the number of parallel threads you wish to run for testing.
+
+#### Measuring code coverage
+
+Code coverage can be measured as follows:
+
+```shell
+py.test --cov=cmd2 --cov-report term-missing --cov-report=html
+```
+
+Then use your web browser of choice to look at the results which are in `<cmd2>/htmlcov/index.html`.
+
+### Squash Your Commits
+When you make a pull request, it is preferable for all of your changes to be in one commit.
+
+If you have made more then one commit, then you will can _squash_ your commits.
+
+To do this, see [Squashing Your Commits](http://forum.freecodecamp.com/t/how-to-squash-multiple-commits-into-one-with-git/13231).
+
+### Creating A Pull Request
+
+#### What is a Pull Request?
+
+A pull request (PR) is a method of submitting proposed changes to the cmd2
+Repo (or any Repo, for that matter). You will make changes to copies of the
+files which make up cmd2 in a personal fork, then apply to have them
+accepted by cmd2 proper.
+
+#### Need Help?
+
+GitHub has a good guide on how to contribute to open source [here](https://opensource.guide/how-to-contribute/).
+
+#### Important: ALWAYS EDIT ON A BRANCH
+
+Take away only one thing from this document, it should be this: Never, **EVER**
+make edits to the `master` branch. ALWAYS make a new branch BEFORE you edit
+files. This is critical, because if your PR is not accepted, your copy of
+master will be forever sullied and the only way to fix it is to delete your
+fork and re-fork.
+
+#### Methods
+
+There are two methods of creating a pull request for cmd2:
+
+-   Editing files on a local clone (recommended)
+-   Editing files via the GitHub Interface
+
+##### Method 1: Editing via your Local Fork _(Recommended)_
+
+This is the recommended method. Read about [How to Setup and Maintain a Local
+Instance of cmd2](#maintaining-your-fork).
+
+1.  Perform the maintenance step of rebasing `master`.
+2.  Ensure you are on the `master` branch using `git status`:
+
+```bash
+$ git status
+On branch master
+Your branch is up-to-date with 'origin/master'.
+
+nothing to commit, working directory clean
+```
+
+1.  If you are not on master or your working directory is not clean, resolve
+    any outstanding files/commits and checkout master `git checkout master`
+
+2.  Create a branch off of `master` with git: `git checkout -B
+    branch/name-here` **Note:** Branch naming is important. Use a name like
+    `fix/short-fix-description` or `feature/short-feature-description`. Review
+     the [Contribution Guidelines](#contribution-guidelines) for more detail.
+
+3.  Edit your file(s) locally with the editor of your choice
+
+4.  Check your `git status` to see unstaged files.
+
+5.  Add your edited files: `git add path/to/filename.ext` You can also do: `git
+    add .` to add all unstaged files. Take care, though, because you can
+    accidentally add files you don't want added. Review your `git status` first.
+
+6.  Commit your edits: `git commit -m "Brief Description of Commit"`. Do not add the issue number in the commit message.
+
+7.  Squash your commits, if there are more than one.
+
+8.  Push your commits to your GitHub Fork: `git push -u origin branch/name-here`
+
+9.  Go to [Common Steps](#common-steps)
+
+##### Method 2: Editing via the GitHub Interface
+
+Note: Editing via the GitHub Interface is not recommended, since it is not
+possible to update your fork via GitHub's interface without deleting and
+recreating your fork.
+
+If you really want to go this route which isn't recommended, you can Google for more information on
+how to do it.
+
+### Common Steps
+
+1.  Once the edits have been committed, you will be prompted to create a pull
+    request on your fork's GitHub Page.
+
+2.  By default, all pull requests should be against the cmd2 main repo, `master`
+    branch.
+
+3.  Submit a pull request from your branch to cmd2's `master` branch.
+
+4.  The title (also called the subject) of your PR should be descriptive of your
+    changes and succinctly indicates what is being fixed.
+
+    -   **Do not add the issue number in the PR title or commit message.**
+
+    -   Examples: `Add Test Cases for Unicode Support` `Correct typo in Overview documentation`
+
+5.  In the body of your PR include a more detailed summary of the changes you
+    made and why.
+
+    -   If the PR is meant to fix an existing bug/issue, then, at the end of
+        your PR's description, append the keyword `closes` and #xxxx (where xxxx
+        is the issue number). Example: `closes #1337`. This tells GitHub to
+        close the existing issue, if the PR is merged.
+
+6.  Indicate what local testing you have done (e.g. what OS and version(s) of Python did you run the
+    unit test suite with)
+
+
+### How We Review and Merge Pull Requests
+
+cmd2 has a team of volunteer Maintainers. These Maintainers routinely go through open pull requests in a process called [Quality Assurance](https://en.wikipedia.org/wiki/Quality_assurance) (QA).  We also utilize multiple continuous
+integration (CI) providers to automatically run all of the unit tests on multiple operating systems and versions of Python.
+
+1. If your changes can merge without conflicts and all unit tests pass for all OSes and supported versions of Python,
+then your pull request (PR) will have a big green checkbox which says something like "All Checks Passed" next to it.
+If this is not the case, there will be a link you can click on to get details regarding what the problem is.  
+It is your responsibility to make sure all unit tests are passing.  Generally a Maintainer will not QA a
+pull request unless it can merge without conflicts and all unit tests pass on all supported platforms.
+
+2. If a Maintainer QA's a pull request and confirms that the new code does what it is supposed to do without seeming to introduce any new bugs,
+and doesn't present any backward compatibility issues, they will merge the pull request.
+
+If you would like to apply to join our Maintainer team, message [@FedericoCeratto](https://github.com/FedericoCeratto) with links to 5 of your pull requests that have been accepted.
+
+
+### How We Close Stale Issues
+
+We will close any issues that have been inactive for more than 60 days or pull requests that have been
+inactive for more than 30 days, except those that match the following criteria:
+- bugs that are confirmed
+- pull requests that are waiting on other pull requests to be merged
+- features that are part of a cmd2 GitHub Milestone or Project
+
+### Next Steps
+
+#### If your PR is accepted
+
+Once your PR is accepted, you may delete the branch you created to submit it.
+This keeps your working fork clean.
+
+You can do this with a press of a button on the GitHub PR interface. You can
+delete the local copy of the branch with: `git branch -D branch/to-delete-name`
+
+#### If your PR is rejected
+
+Don't despair! You should receive solid feedback from the Maintainers as to
+why it was rejected and what changes are needed.
+
+Many Pull Requests, especially first Pull Requests, require correction or
+updating. If you have used the GitHub interface to create your PR, you will need
+to close your PR, create a new branch, and re-submit.
+
+If you have a local copy of the repo, you can make the requested changes and
+amend your commit with: `git commit --amend` This will update your existing
+commit. When you push it to your fork you will need to do a force push to
+overwrite your old commit: `git push --force`
+
+Be sure to post in the PR conversation that you have made the requested changes.
+
+### Other resources
+
+-   [PEP8 Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/)
+
+-   [Searching for Your Issue on GitHub](https://help.github.com/articles/searching-issues/)
+
+-   [Creating a New GitHub Issue](https://help.github.com/articles/creating-an-issue/)
+
+### Advice
+
+Here is some advice regarding what makes a good pull request (PR) from the perspective of the cmd2 maintainers:
+- Multiple smaller PRs divided by topic are better than a single large PR containing a bunch of unrelated changes
+- Maintaining backward compatibility is important
+- Good unit/functional tests are very important
+- Accurate documentation is also important
+- Adding new features is of the lowest importance, behind bug fixes, unit test additions/improvements, code cleanup, and documentation
+- It's best to create a dedicated branch for a PR and use it only for that PR (and delete it once the PR has been merged)
+- It's good if the branch name is related to the PR contents, even if it's just "fix123" or "add_more_tests"
+- Code coverage of the unit tests matters, try not to decrease it
+- Think twice before adding dependencies to 3rd party libraries (outside of the Python standard library) because it could affect a lot of users
+
+### Acknowledgement
+Thanks to the good folks at [freeCodeCamp](https://github.com/freeCodeCamp/freeCodeCamp) for creating
+an excellent `CONTRIBUTING` file which we have borrowed heavily from.
diff --git a/README.rst b/README.rst
index 5d2bac51..eed16071 100755
--- a/README.rst
+++ b/README.rst
@@ -124,7 +124,7 @@ A couple tutorials on using cmd2 exist:
 Example Application

 -------------------

 

-Example cmd2 application (**example/example.py**) ::

+Example cmd2 application (**examples/example.py**) ::

 

     '''A sample application for cmd2.'''

 

diff --git a/cmd2.py b/cmd2.py
index 057b6390..ae39d568 100755
--- a/cmd2.py
+++ b/cmd2.py
@@ -14,7 +14,7 @@ Settable environment parameters
 Optional _onchange_{paramname} called when environment parameter changes
 Parsing commands with `optparse` options (flags)
 Redirection to file with >, >>; input from file with <
-Easy transcript-based testing of applications (see example/example.py)
+Easy transcript-based testing of applications (see examples/example.py)
 Bash-style ``select`` available
 
 Note that redirection with > and | will only work if `self.stdout.write()`
diff --git a/example/example.py b/examples/example.py
index f39be5de..f39be5de 100755
--- a/example/example.py
+++ b/examples/example.py
diff --git a/example/exampleSession.txt b/examples/exampleSession.txt
index a4eef91f..a4eef91f 100644
--- a/example/exampleSession.txt
+++ b/examples/exampleSession.txt
diff --git a/example/script.py b/examples/script.py
index 7d0c998a..7d0c998a 100644
--- a/example/script.py
+++ b/examples/script.py
diff --git a/example/script.txt b/examples/script.txt
index 1e18262a..1e18262a 100644
--- a/example/script.txt
+++ b/examples/script.txt
diff --git a/setup.py b/setup.py
index b5923430..fb7a9590 100755
--- a/setup.py
+++ b/setup.py
@@ -28,7 +28,7 @@ Drop-in replacement adds several features for command-prompt tools:
     * bare >, >>, < redirect to/from paste buffer
     * accepts abbreviated commands when unambiguous
     * `py` enters interactive Python console
-    * test apps against sample session transcript (see example/example.py)
+    * test apps against sample session transcript (see examples/example.py)
 
 Useable without modification anywhere cmd is used; simply import cmd2.Cmd in place of cmd.Cmd.
 """
diff --git a/tox.ini b/tox.ini
index 14b0b062..516d1796 100644
--- a/tox.ini
+++ b/tox.ini
@@ -9,5 +9,5 @@ deps =
   six
 commands=
   py.test -v --basetemp={envtmpdir} {posargs}
-  {envpython} example/example.py --test example/exampleSession.txt
+  {envpython} examples/example.py --test examples/exampleSession.txt