--- /dev/null
+
+CONTENTS OF THIS FILE
+---------------------
+ * Introduction
+ * Usage
+ * Requirements
+ * Installation
+ * Troubleshooting
+ * FAQ
+ * Maintainers
+
+
+INTRODUCTION
+------------
+
+Drupal Module Upgrader is a script that scans the source of a Drupal 7 module,
+flags any code that requires updating to Drupal 8, points off to any relevant
+API change notices from https://www.drupal.org/list-changes/, and (where
+possible) will actually attempt to *convert* the Drupal 7 code automatically to
+the Drupal 8 version!
+
+ * For a full description of the module, visit the project page:
+ https://drupal.org/project/drupalmoduleupgrader
+ * To submit bug reports and feature suggestions, or to track changes:
+ https://drupal.org/project/issues/drupalmoduleupgrader
+
+
+USAGE
+-----
+
+1. Place the Drupal 7 module you wish to port into your Drupal 8 site's
+ /modules directory.
+
+2. To scan the code and get a report of code that needs updating and how, run
+ the following inside the Drupal 8 root directory:
+
+ drush dmu-analyze MODULE_NAME
+
+ This will print a report showing any relevant change notices where you can
+ read more.
+
+3. To attempt to upgrade your Drupal 7 module's code to Drupal 8 automatically,
+ run the following inside the Drupal 8 root directory:
+
+ drush dmu-upgrade MODULE_NAME
+
+ The script will output a few lines as it attempts various conversions. Go
+ into your modules/MODULE_NAME directory and check out all of your new YAML
+ files and such. ;)
+
+4. To clear out D7 code that has been converted, run the clean command:
+
+ drush dmu-clean MODULE_NAME
+
+ This will do things like delete old .info files and such, so you're closer to
+ your port being completed!
+
+REQUIREMENTS
+------------
+This project requires the following dependencies:
+
+ * Composer (https://getcomposer.org)
+ * Drush 7+ (https://github.com/drush-ops/drush)
+ * Pharborist (https://github.com/grom358/pharborist)
+ * Symfony Yaml Component (https://github.com/symfony/Yaml)
+
+Note that most dependencies are automatically downloaded by Composer during
+installation.
+
+
+INSTALLATION
+------------
+
+0. Download and install Composer:
+
+ https://getcomposer.org/doc/00-intro.md#system-requirements
+
+1. Download and install the latest version of Drush:
+
+ https://github.com/drush-ops/drush#installupdate---composer
+
+2. Download and install the latest Drupal 8:
+
+ git clone --branch 8.0.x http://git.drupal.org/project/drupal.git 8.x
+
+3. Download the latest release of drupalmoduleupgrader to your Drupal 8 site’s
+ /modules directory:
+
+ drush dl drupalmoduleupgrader
+
+4. Run `composer install` from the drupalmoduleupgrader directory:
+
+ cd drupalmoduleupgrader
+ composer install
+
+ You should see output as it downloads various dependencies (pharborist,
+ phpcs, yaml...)
+
+5. Finally, enable the module:
+
+ drush en drupalmoduleupgrader -y
+
+
+TROUBLESHOOTING
+---------------
+ * If you are getting any errors, check the following first:
+ - Are you using the very latest Drupal 8 code? From the 8.x root directory,
+ do:
+ git pull --rebase
+ - Are you using the very latest drupalmoduleupgrader code (and dependencies'
+ code)? From the drupalmoduleupgrader root directory:
+ git pull --rebase
+ composer update
+ drush pm-uninstall drupalmoduleupgrader -y
+ drush en drupalmoduleupgrader
+
+
+RUNNING TESTS
+-------------
+
+Drupal Module Upgrader uses Composer to install its dependencies inside the
+module folder. Since it operates as a standalone project this is perfectly
+fine. However if we want to run the tests we have to use a different strategy.
+Drupal core itself also uses Composer, and it manages its dependencies and
+namespaces inside the core/vendor/ folder. It is unaware of DMU's dependencies
+and the tests will fail.
+
+We can use Composer Manager [1] to generate a new composer.json file in the
+root of the Drupal site. This will combine the dependencies of Drupal core and
+all contributed and custom projects.
+
+
+0. Navigate to the root folder of your Drupal installation:
+
+ cd /path/to/drupal/site/
+
+1. Download Composer Manager:
+
+ drush dl composer_manager
+
+2. Initialize Composer Manager:
+
+ php modules/composer_manager/scripts/init.php
+
+3. Install the combined dependencies of Drupal core and modules:
+
+ composer drupal-install
+
+4. Run the tests:
+
+ ./vendor/bin/phpunit -c core --group=DMU
+
+
+FAQ
+---
+Q: Wow, this thing is awesome! How does it work under the hood?
+A: You're in luck! We have documentation describing DMU's overall architecture
+ and how to contribute:
+ https://www.drupal.org/documentation/modules/drupalmoduleupgrader/contributors
+
+MAINTAINERS
+-----------
+Current maintainers:
+ * Adam (phenaproxima) - https://www.drupal.org/u/phenaproxima
+ * Angela Byron (webchick) - https://www.drupal.org/u/webchick
+
+Past maintainers:
+ * Gábor Hojtsy - https://www.drupal.org/u/gábor-hojtsy
+ * Jakob Perry (japerry) - https://www.drupal.org/u/japerry
+ * Jess (xjm) - https://www.drupal.org/u/xjm
+ * Lisa Baker (eshta) - https://www.drupal.org/u/eshta
+ * Wim Leers - https://www.drupal.org/u/wim-leers
+
+Special thanks to:
+ * Cameron Zemek (grom358) - https://www.drupal.org/u/grom358 for all the
+ pharborist help!
+
+This project has been sponsored by:
+* Acquia
+ Dream It. Drupal It. https://www.acquia.com
+
+This project has been supported by:
+* PreviousNext
+ Australia’s premium Drupal website consulting, design and development firm.
+ http://www.previousnext.com.au/
+
+
+REFERENCES
+----------
+[1] Composer Manager: https://www.drupal.org/project/composer_manager