README.rst

   1 Moodle Development Kit
   2 ======================
   3
   4 A collection of tools meant to make developers' lives easier.
   5
   6 Requirements
   7 ============
   8
   9 - Linux or Mac OS
  10 - Python 2.7
  11 - MySQL, MariaDB or PostgreSQL
  12 - Git v1.7.7 or greater
  13
  14 Most of the tools work on Moodle 1.9 onwards, but some CLI scripts required by MDK might not be available in all versions.
  15
  16 Usage
  17 =====
  18
  19 The commands are called using that form::
  20
  21     mdk <command> <arguments>
  22
  23 Get some help on a command using::
  24
  25     mdk <command> --help
  26
  27 Also check the `wiki <https://github.com/FMCorz/mdk/wiki>`_.
  28
  29 Installation
  30 ============
  31
  32 Python package
  33 --------------
  34
  35 You need the `pip <http://www.pip-installer.org/en/latest/installing.html>`_ to do this::
  36
  37     sudo pip install moodle-sdk
  38     mdk init
  39
  40 That's it!
  41
  42 On Debian-based systems, you will probably need to install the following packages:
  43
  44     sudo apt-get install python-pip libmysqlclient-dev libpq-dev python-dev
  45
  46
  47 Homebrew
  48 --------
  49
  50 Using `Homebrew <http://brew.sh/>`_, please refer to this `formula <https://github.com/danpoltawski/homebrew-mdk>`_.
  51
  52
  53 Git
  54 ---
  55
  56 1. Clone the repository
  57 ~~~~~~~~~~~~~~~~~~~~~~~
  58
  59 ::
  60
  61     cd /opt
  62     sudo git clone git://github.com/FMCorz/mdk.git moodle-sdk
  63
  64 2. Install the dependencies
  65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  66
  67 You will need the tool `pip <http://www.pip-installer.org/en/latest/installing.html>`_ to install the packages required by Python.
  68
  69 ::
  70
  71     sudo pip install -r /opt/moodle-sdk/requirements.txt
  72
  73 On Debian-based systems, you will probably need to install the following packages:
  74
  75     sudo apt-get install python-pip libmysqlclient-dev libpq-dev python-dev
  76
  77 3. Make executable and accessible
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 ::
  81
  82     sudo chmod +x /opt/moodle-sdk/mdk.py
  83     sudo ln -s /opt/moodle-sdk/mdk.py /usr/local/bin/mdk
  84
  85 4. Set up the basics
  86 ~~~~~~~~~~~~~~~~~~~~
  87
  88 Assuming that you are using Apache, which is set up to serve the files from /var/www, leave the default values as they are in ``mdk init``, except for your remote and the database passwords.
  89
  90 ::
  91
  92     mkdir ~/www
  93     sudo ln -s ~/www /var/www/m
  94     mdk init
  95
  96 You're all set.
  97
  98 Optional
  99 ~~~~~~~~
 100
 101 To activate bash completion::
 102
 103     sudo ln -s /opt/moodle-sdk/extra/bash_completion /etc/bash_completion.d/moodle-sdk
 104
 105 To activate goto commands (``gt`` and ``gtd``), add the following to ~/.bashrc::
 106
 107     if [ -f /opt/moodle-sdk/extra/goto_instance ]; then
 108         . /opt/moodle-sdk/extra/goto_instance
 109         . /opt/moodle-sdk/extra/goto_instance.bash_completion
 110     fi
 111
 112
 113 Command list
 114 ============
 115
 116 alias
 117 -----
 118
 119 Set up aliases of your Moodle commands.
 120
 121 **Example**
 122
 123 This line defines the alias 'upall', for 'moodle update --all'
 124
 125 ::
 126
 127     mdk alias add upall "update --all"
 128
 129 backport
 130 --------
 131
 132 Backport a branch to another instance of Moodle.
 133
 134 **Examples**
 135
 136 Assuming we are in a Moodle instance, this backports the current branch to the version 2.2 and 2.3
 137
 138 ::
 139
 140     mdk backport --version 22 23
 141
 142 Backports the branch MDL-12345-23 from the instance stable_23 to the instance stable_22, and pushes the new branch to your remote
 143
 144 ::
 145
 146     mdk backport stable_23 --branch MDL-12345-23 --version 22 --push
 147
 148 backup
 149 ------
 150
 151 Backup a whole instance so that it can be restored later.
 152
 153 **Examples**
 154
 155 Backup the instance named stable_master
 156
 157 ::
 158
 159     mdk backup stable_master
 160
 161 List the backups
 162
 163 ::
 164
 165     mdk backup --list
 166
 167 Restore the second backup of the instance stable_master
 168
 169 ::
 170
 171     mdk backup --restore stable_master_02
 172
 173
 174 behat
 175 -----
 176
 177 Get the instance ready for acceptance testing (Behat), and run the test feature(s).
 178
 179 **Examples**
 180
 181 ::
 182
 183     mdk behat -r --tags=@core_completion
 184
 185
 186 create
 187 ------
 188
 189 Create a new instance of Moodle. It will be named according to your config file.
 190
 191 **Examples**
 192
 193 Create a new instance of Moodle 2.1
 194
 195 ::
 196
 197     mdk create --version 21
 198
 199 Create an instance of Moodle 2.2 using PostgreSQL from the integration remote, and run the installation script.
 200
 201 ::
 202
 203     mdk create --version 22 --engine pgsql --integration --install
 204
 205 config
 206 ------
 207
 208 Set your MDK settings from the command line.
 209
 210 **Examples**
 211
 212 Show the list of your settings
 213
 214 ::
 215
 216     mdk config list
 217
 218 Change the value of the setting ``dirs.storage`` to ``/var/www/repositories``
 219
 220 ::
 221
 222     mdk config set dirs.storage /var/www/repositories
 223
 224
 225 css
 226 ---
 227
 228 CSS related functions.
 229
 230 **Example**
 231
 232 Compile the LESS files from Bootstrapbase
 233
 234 ::
 235
 236     mdk css --compile
 237
 238
 239 doctor
 240 ------
 241
 242 Perform some checks on the environment to identify possible problems, and attempt to fix them automatically.
 243
 244
 245 fix
 246 ---
 247
 248 Create a branch from an issue number on the tracker (MDL-12345) and sets it to track the right branch.
 249
 250 **Examples**
 251
 252 In a Moodle 2.2 instance, this will create (and checkout) a branch named MDL-12345-22 which will track upstream/MOODLE_22_STABLE.
 253
 254 ::
 255
 256     mdk fix MDL-12345
 257     mdk fix 12345
 258
 259
 260 info
 261 ----
 262
 263 Display information about the instances on the system.
 264
 265 **Examples**
 266
 267 List the instances
 268
 269 ::
 270
 271     mdk info --list
 272
 273 Display the information known about the instance *stable_master*
 274
 275 ::
 276
 277     mdk info stable_master
 278
 279
 280 install
 281 -------
 282
 283 Run the command line installation script with all parameters set on an existing instance.
 284
 285 **Examples**
 286
 287 ::
 288
 289     mdk install --engine mysqli stable_master
 290
 291
 292 js
 293 --
 294
 295 JS related functions.
 296
 297 **Example**
 298
 299 Compile the JS modules in Atto
 300
 301 ::
 302
 303     mdk js shift --plugin editor_atto
 304
 305
 306 Generate the complete YUI API documentation
 307
 308     mdk js doc
 309
 310
 311 phpunit
 312 -------
 313
 314 Get the instance ready for PHPUnit tests, and run the test(s).
 315
 316 **Examples**
 317
 318 ::
 319
 320     mdk phpunit -u repository/tests/repository_test.php
 321
 322
 323 plugin
 324 ------
 325
 326 Look for a plugin on moodle.org and downloads it into your instance.
 327
 328 **Example**
 329
 330 ::
 331
 332     mdk plugin download repository_evernote
 333
 334
 335 purge
 336 -----
 337
 338 Purge the cache.
 339
 340 **Example**
 341
 342 To purge the cache of all the instances
 343
 344 ::
 345
 346     mdk purge --all
 347
 348
 349 pull
 350 ----
 351
 352 Pulls a patch using the information from a tracker issue.
 353
 354 **Example**
 355
 356 Assuming we type that command on a 2.3 instance, pulls the corresponding patch from the issue MDL-12345 in a testing branch
 357
 358 ::
 359
 360     mdk pull --testing 12345
 361
 362
 363 push
 364 ----
 365
 366 Shortcut to push a branch to your remote.
 367
 368 **Examples**
 369
 370 Push the current branch to your repository
 371
 372 ::
 373
 374     mdk push
 375
 376 Force a push of the branch MDL-12345-22 from the instance stable_22 to your remote
 377
 378 ::
 379
 380     mdk push --force --branch MDL-12345-22 stable_22
 381
 382
 383 rebase
 384 ------
 385
 386 Fetch the latest branches from the upstream remote and rebase your local branches.
 387
 388 **Examples**
 389
 390 This will rebase the branches MDL-12345-xx and MDL-56789-xx on the instances stable_22, stable_23 and stable_master. And push them to your remote if successful.
 391
 392 ::
 393
 394     mdk rebase --issues 12345 56789 --version 22 23 master --push
 395     mdk rebase --issues MDL-12345 MDL-56789 --push stable_22 stable_23 stable_master
 396
 397
 398 remove
 399 ------
 400
 401 Remove an instance, deleting every thing including the database.
 402
 403 **Example**
 404
 405 ::
 406
 407     mdk remove stable_master
 408
 409
 410 run
 411 ---
 412
 413 Execute a script on an instance. The scripts are stored in the scripts directory.
 414
 415 **Example**
 416
 417 Set the instance stable_master ready for development
 418
 419 ::
 420
 421     mdk run dev stable_master
 422
 423
 424 tracker
 425 -------
 426
 427 Gets some information about the issue on the tracker.
 428
 429 **Example**
 430
 431 ::
 432
 433     $ mdk tracker 34543
 434     ------------------------------------------------------------------------
 435       MDL-34543: New assignment module - Feedback file exists for an
 436         assignment but not shown in the Feedback files picker
 437       Bug - Critical - https://tracker.moodle.org/browse/MDL-34543
 438       Closed (Fixed) 2012-08-17 07:25
 439     -------------------------------------------------------[ V: 7 - W: 7 ]--
 440     Reporter            : Paul Hague (paulhague) on 2012-07-26 08:30
 441     Assignee            : Eric Merrill (emerrill)
 442     Peer reviewer       : Damyon Wiese (damyon)
 443     Integrator          : Dan Poltawski (poltawski)
 444     Tester              : Tim Barker (timb)
 445     ------------------------------------------------------------------------
 446
 447
 448 uninstall
 449 ---------
 450
 451 Uninstall an instance: removes config file, drops the database, deletes dataroot content, ...
 452
 453
 454 update
 455 ------
 456
 457 Fetch the latest stables branches from the upstream remote and pull the changes into the local stable branch.
 458
 459 **Examples**
 460
 461 This updates the instances stable_22 and stable_23
 462
 463 ::
 464
 465     mdk update stable_22 stable_23
 466
 467 This updates all your integration instances and runs the upgrade script of Moodle.
 468
 469 ::
 470
 471     mdk update --integration --upgrade
 472
 473
 474 upgrade
 475 -------
 476
 477 Run the upgrade script of your instance.
 478
 479 **Examples**
 480
 481 The following runs an upgrade on your stable branches
 482
 483 ::
 484
 485     mdk upgrade --stable
 486
 487 This will run an update an each instance before performing the upgrade process
 488
 489 ::
 490
 491     mdk upgrade --all --update
 492
 493 Scripts
 494 =======
 495
 496 You can write custom scripts and execute them on your instances using the command ``mdk run``. MDK looks for the scripts in the *scripts* directories and identifies their type by reading their extension. For example, a script called 'helloworld.php' will be executed as a command line script from the root of an installation.
 497
 498 ::
 499
 500     # From anywhere on the system
 501     $ mdk run helloworld stable_master
 502
 503     # Is similar to typing the following command
 504     $ cp /path/to/script/helloworld.php /path/to/moodle/instances/stable_master
 505     $ cd /path/to/moodle/instances/stable_master
 506     $ php helloworld.php
 507
 508 Scripts are very handy when it comes to performing more complexed tasks.
 509
 510 Shipped scripts
 511 ---------------
 512
 513 The following scripts are available with MDK:
 514
 515 * ``dev``: Changes a portion of Moodle settings to enable development mode
 516 * ``enrol``: Enrols users in any existing course
 517 * ``undev``: Reverts the changes made by ``dev``
 518 * ``users``: Creates a set of users
 519 * ``webservices``: Does all the set up of webservices for you
 520
 521 License
 522 =======
 523
 524 Licensed under the `GNU GPL License <http://www.gnu.org/copyleft/gpl.html>`_