www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/drupalmoduleupgrader/README.txt

   1
   2 CONTENTS OF THIS FILE
   3 ---------------------
   4  * Introduction
   5  * Usage
   6  * Requirements
   7  * Installation
   8  * Troubleshooting
   9  * FAQ
  10  * Maintainers
  11
  12
  13 INTRODUCTION
  14 ------------
  15
  16 Drupal Module Upgrader is a script that scans the source of a Drupal 7 module,
  17 flags any code that requires updating to Drupal 8, points off to any relevant
  18 API change notices from https://www.drupal.org/list-changes/, and (where
  19 possible) will actually attempt to *convert* the Drupal 7 code automatically to
  20 the Drupal 8 version!
  21
  22  * For a full description of the module, visit the project page:
  23    https://drupal.org/project/drupalmoduleupgrader
  24  * To submit bug reports and feature suggestions, or to track changes:
  25    https://drupal.org/project/issues/drupalmoduleupgrader
  26
  27
  28 USAGE
  29 -----
  30
  31 1. Place the Drupal 7 module you wish to port into your Drupal 8 site's
  32    /modules directory.
  33
  34 2. To scan the code and get a report of code that needs updating and how, run
  35    the following inside the Drupal 8 root directory:
  36
  37    drush dmu-analyze MODULE_NAME
  38
  39    This will print a report showing any relevant change notices where you can
  40    read more.
  41
  42 3. To attempt to upgrade your Drupal 7 module's code to Drupal 8 automatically,
  43    run the following inside the Drupal 8 root directory:
  44
  45    drush dmu-upgrade MODULE_NAME
  46
  47    The script will output a few lines as it attempts various conversions. Go
  48    into your modules/MODULE_NAME directory and check out all of your new YAML
  49    files and such. ;)
  50
  51 4. To clear out D7 code that has been converted, run the clean command:
  52
  53    drush dmu-clean MODULE_NAME
  54
  55    This will do things like delete old .info files and such, so you're closer to
  56    your port being completed!
  57
  58 REQUIREMENTS
  59 ------------
  60 This project requires the following dependencies:
  61
  62  * Composer (https://getcomposer.org)
  63  * Drush 7+ (https://github.com/drush-ops/drush)
  64  * Pharborist (https://github.com/grom358/pharborist)
  65  * Symfony Yaml Component (https://github.com/symfony/Yaml)
  66
  67 Note that most dependencies are automatically downloaded by Composer during
  68 installation.
  69
  70
  71 INSTALLATION
  72 ------------
  73
  74 0. Download and install Composer:
  75
  76    https://getcomposer.org/doc/00-intro.md#system-requirements
  77
  78 1. Download and install the latest version of Drush:
  79
  80    https://github.com/drush-ops/drush#installupdate---composer
  81
  82 2. Download and install the latest Drupal 8:
  83
  84    git clone --branch 8.0.x http://git.drupal.org/project/drupal.git 8.x
  85
  86 3. Download the latest release of drupalmoduleupgrader to your Drupal 8 site’s
  87    /modules directory:
  88
  89    drush dl drupalmoduleupgrader
  90
  91 4. Run `composer install` from the drupalmoduleupgrader directory:
  92
  93    cd drupalmoduleupgrader
  94    composer install
  95
  96    You should see output as it downloads various dependencies (pharborist,
  97    phpcs, yaml...)
  98
  99 5. Finally, enable the module:
 100
 101    drush en drupalmoduleupgrader -y
 102
 103
 104 TROUBLESHOOTING
 105 ---------------
 106  * If you are getting any errors, check the following first:
 107    - Are you using the very latest Drupal 8 code? From the 8.x root directory,
 108      do:
 109        git pull --rebase
 110    - Are you using the very latest drupalmoduleupgrader code (and dependencies'
 111      code)? From the drupalmoduleupgrader root directory:
 112        git pull --rebase
 113        composer update
 114        drush pm-uninstall drupalmoduleupgrader -y
 115        drush en drupalmoduleupgrader
 116
 117
 118 RUNNING TESTS
 119 -------------
 120
 121 Drupal Module Upgrader uses Composer to install its dependencies inside the
 122 module folder. Since it operates as a standalone project this is perfectly
 123 fine. However if we want to run the tests we have to use a different strategy.
 124 Drupal core itself also uses Composer, and it manages its dependencies and
 125 namespaces inside the core/vendor/ folder. It is unaware of DMU's dependencies
 126 and the tests will fail.
 127
 128 We can use Composer Manager [1] to generate a new composer.json file in the
 129 root of the Drupal site. This will combine the dependencies of Drupal core and
 130 all contributed and custom projects.
 131
 132
 133 0. Navigate to the root folder of your Drupal installation:
 134
 135    cd /path/to/drupal/site/
 136
 137 1. Download Composer Manager:
 138
 139    drush dl composer_manager
 140
 141 2. Initialize Composer Manager:
 142
 143    php modules/composer_manager/scripts/init.php
 144
 145 3. Install the combined dependencies of Drupal core and modules:
 146
 147    composer drupal-install
 148
 149 4. Run the tests:
 150
 151   ./vendor/bin/phpunit -c core --group=DMU
 152
 153
 154 FAQ
 155 ---
 156 Q: Wow, this thing is awesome! How does it work under the hood?
 157 A: You're in luck! We have documentation describing DMU's overall architecture
 158    and how to contribute:
 159    https://www.drupal.org/documentation/modules/drupalmoduleupgrader/contributors
 160
 161 MAINTAINERS
 162 -----------
 163 Current maintainers:
 164  * Adam (phenaproxima) - https://www.drupal.org/u/phenaproxima
 165  * Angela Byron (webchick) - https://www.drupal.org/u/webchick
 166
 167 Past maintainers:
 168  * Gábor Hojtsy - https://www.drupal.org/u/gábor-hojtsy
 169  * Jakob Perry (japerry) - https://www.drupal.org/u/japerry
 170  * Jess (xjm) - https://www.drupal.org/u/xjm
 171  * Lisa Baker (eshta) - https://www.drupal.org/u/eshta
 172  * Wim Leers - https://www.drupal.org/u/wim-leers
 173
 174 Special thanks to:
 175  * Cameron Zemek (grom358) - https://www.drupal.org/u/grom358 for all the
 176    pharborist help!
 177
 178 This project has been sponsored by:
 179 * Acquia
 180   Dream It. Drupal It. https://www.acquia.com
 181
 182 This project has been supported by:
 183 * PreviousNext
 184   Australia’s premium Drupal website consulting, design and development firm.
 185   http://www.previousnext.com.au/
 186
 187
 188 REFERENCES
 189 ----------
 190 [1] Composer Manager: https://www.drupal.org/project/composer_manager