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 Clone the repository
  57 ~~~~~~~~~~~~~~~~~~~~
  58
  59 ::
  60
  61     cd /opt
  62     sudo git clone git://github.com/FMCorz/mdk.git moodle-sdk
  63
  64 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 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 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 Upgrading
 114 =========
 115
 116 If you installed MDK using PIP, run the following command::
 117
 118     sudo pip install --upgrade moodle-sdk
 119
 120 It is possible that a new version of MDK requires new files, directories, etc... and while we try to make it easy to upgrade, it can happen that some features get broken in your environment. So after each upgrade, consider running the following to get more information::
 121
 122     mdk doctor --all
 123
 124
 125 Command list
 126 ============
 127
 128 alias
 129 -----
 130
 131 Set up aliases of your Moodle commands.
 132
 133 **Example**
 134
 135 This line defines the alias 'upall', for 'moodle update --all'
 136
 137 ::
 138
 139     mdk alias add upall "update --all"
 140
 141 backport
 142 --------
 143
 144 Backport a branch to another instance of Moodle.
 145
 146 **Examples**
 147
 148 Assuming we are in a Moodle instance, this backports the current branch to the version 2.2 and 2.3
 149
 150 ::
 151
 152     mdk backport --version 22 23
 153
 154 Backports the branch MDL-12345-23 from the instance stable_23 to the instance stable_22, and pushes the new branch to your remote
 155
 156 ::
 157
 158     mdk backport stable_23 --branch MDL-12345-23 --version 22 --push
 159
 160 backup
 161 ------
 162
 163 Backup a whole instance so that it can be restored later.
 164
 165 **Examples**
 166
 167 Backup the instance named stable_master
 168
 169 ::
 170
 171     mdk backup stable_master
 172
 173 List the backups
 174
 175 ::
 176
 177     mdk backup --list
 178
 179 Restore the second backup of the instance stable_master
 180
 181 ::
 182
 183     mdk backup --restore stable_master_02
 184
 185
 186 behat
 187 -----
 188
 189 Get the instance ready for acceptance testing (Behat), and run the test feature(s).
 190
 191 **Examples**
 192
 193 ::
 194
 195     mdk behat -r --tags=@core_completion
 196
 197
 198 create
 199 ------
 200
 201 Create a new instance of Moodle. It will be named according to your config file.
 202
 203 **Examples**
 204
 205 Create a new instance of Moodle 2.1
 206
 207 ::
 208
 209     mdk create --version 21
 210
 211 Create an instance of Moodle 2.2 using PostgreSQL from the integration remote, and run the installation script.
 212
 213 ::
 214
 215     mdk create --version 22 --engine pgsql --integration --install
 216
 217 config
 218 ------
 219
 220 Set your MDK settings from the command line.
 221
 222 **Examples**
 223
 224 Show the list of your settings
 225
 226 ::
 227
 228     mdk config list
 229
 230 Change the value of the setting ``dirs.storage`` to ``/var/www/repositories``
 231
 232 ::
 233
 234     mdk config set dirs.storage /var/www/repositories
 235
 236
 237 css
 238 ---
 239
 240 CSS related functions.
 241
 242 **Example**
 243
 244 Compile the LESS files from Bootstrapbase
 245
 246 ::
 247
 248     mdk css --compile
 249
 250
 251 doctor
 252 ------
 253
 254 Perform some checks on the environment to identify possible problems, and attempt to fix them automatically.
 255
 256
 257 fix
 258 ---
 259
 260 Create a branch from an issue number on the tracker (MDL-12345) and sets it to track the right branch.
 261
 262 **Examples**
 263
 264 In a Moodle 2.2 instance, this will create (and checkout) a branch named MDL-12345-22 which will track upstream/MOODLE_22_STABLE.
 265
 266 ::
 267
 268     mdk fix MDL-12345
 269     mdk fix 12345
 270
 271
 272 info
 273 ----
 274
 275 Display information about the instances on the system.
 276
 277 **Examples**
 278
 279 List the instances
 280
 281 ::
 282
 283     mdk info --list
 284
 285 Display the information known about the instance *stable_master*
 286
 287 ::
 288
 289     mdk info stable_master
 290
 291
 292 install
 293 -------
 294
 295 Run the command line installation script with all parameters set on an existing instance.
 296
 297 **Examples**
 298
 299 ::
 300
 301     mdk install --engine mysqli stable_master
 302
 303
 304 js
 305 --
 306
 307 JS related functions.
 308
 309 **Example**
 310
 311 Compile the JS modules in Atto
 312
 313 ::
 314
 315     mdk js shift --plugin editor_atto
 316
 317
 318 Generate the complete YUI API documentation
 319
 320     mdk js doc
 321
 322
 323 phpunit
 324 -------
 325
 326 Get the instance ready for PHPUnit tests, and run the test(s).
 327
 328 **Examples**
 329
 330 ::
 331
 332     mdk phpunit -u repository/tests/repository_test.php
 333
 334
 335 plugin
 336 ------
 337
 338 Look for a plugin on moodle.org and downloads it into your instance.
 339
 340 **Example**
 341
 342 ::
 343
 344     mdk plugin download repository_evernote
 345
 346
 347 precheck
 348 --------
 349
 350 Pre-checks a patch on the CI server.
 351
 352 **Example**
 353
 354 ::
 355
 356     mdk precheck
 357
 358
 359 purge
 360 -----
 361
 362 Purge the cache.
 363
 364 **Example**
 365
 366 To purge the cache of all the instances
 367
 368 ::
 369
 370     mdk purge --all
 371
 372
 373 pull
 374 ----
 375
 376 Pulls a patch using the information from a tracker issue.
 377
 378 **Example**
 379
 380 Assuming we type that command on a 2.3 instance, pulls the corresponding patch from the issue MDL-12345 in a testing branch
 381
 382 ::
 383
 384     mdk pull --testing 12345
 385
 386
 387 push
 388 ----
 389
 390 Shortcut to push a branch to your remote.
 391
 392 **Examples**
 393
 394 Push the current branch to your repository
 395
 396 ::
 397
 398     mdk push
 399
 400 Force a push of the branch MDL-12345-22 from the instance stable_22 to your remote
 401
 402 ::
 403
 404     mdk push --force --branch MDL-12345-22 stable_22
 405
 406
 407 rebase
 408 ------
 409
 410 Fetch the latest branches from the upstream remote and rebase your local branches.
 411
 412 **Examples**
 413
 414 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.
 415
 416 ::
 417
 418     mdk rebase --issues 12345 56789 --version 22 23 master --push
 419     mdk rebase --issues MDL-12345 MDL-56789 --push stable_22 stable_23 stable_master
 420
 421
 422 remove
 423 ------
 424
 425 Remove an instance, deleting every thing including the database.
 426
 427 **Example**
 428
 429 ::
 430
 431     mdk remove stable_master
 432
 433
 434 run
 435 ---
 436
 437 Execute a script on an instance. The scripts are stored in the scripts directory.
 438
 439 **Example**
 440
 441 Set the instance stable_master ready for development
 442
 443 ::
 444
 445     mdk run dev stable_master
 446
 447
 448 tracker
 449 -------
 450
 451 Gets some information about the issue on the tracker.
 452
 453 **Example**
 454
 455 ::
 456
 457     $ mdk tracker 34543
 458     ------------------------------------------------------------------------
 459       MDL-34543: New assignment module - Feedback file exists for an
 460         assignment but not shown in the Feedback files picker
 461       Bug - Critical - https://tracker.moodle.org/browse/MDL-34543
 462       Closed (Fixed) 2012-08-17 07:25
 463     -------------------------------------------------------[ V: 7 - W: 7 ]--
 464     Reporter            : Paul Hague (paulhague) on 2012-07-26 08:30
 465     Assignee            : Eric Merrill (emerrill)
 466     Peer reviewer       : Damyon Wiese (damyon)
 467     Integrator          : Dan Poltawski (poltawski)
 468     Tester              : Tim Barker (timb)
 469     ------------------------------------------------------------------------
 470
 471
 472 uninstall
 473 ---------
 474
 475 Uninstall an instance: removes config file, drops the database, deletes dataroot content, ...
 476
 477
 478 update
 479 ------
 480
 481 Fetch the latest stables branches from the upstream remote and pull the changes into the local stable branch.
 482
 483 **Examples**
 484
 485 This updates the instances stable_22 and stable_23
 486
 487 ::
 488
 489     mdk update stable_22 stable_23
 490
 491 This updates all your integration instances and runs the upgrade script of Moodle.
 492
 493 ::
 494
 495     mdk update --integration --upgrade
 496
 497
 498 upgrade
 499 -------
 500
 501 Run the upgrade script of your instance.
 502
 503 **Examples**
 504
 505 The following runs an upgrade on your stable branches
 506
 507 ::
 508
 509     mdk upgrade --stable
 510
 511 This will run an update an each instance before performing the upgrade process
 512
 513 ::
 514
 515     mdk upgrade --all --update
 516
 517 Scripts
 518 =======
 519
 520 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.
 521
 522 ::
 523
 524     # From anywhere on the system
 525     $ mdk run helloworld stable_master
 526
 527     # Is similar to typing the following command
 528     $ cp /path/to/script/helloworld.php /path/to/moodle/instances/stable_master
 529     $ cd /path/to/moodle/instances/stable_master
 530     $ php helloworld.php
 531
 532 Scripts are very handy when it comes to performing more complexed tasks.
 533
 534 Shipped scripts
 535 ---------------
 536
 537 The following scripts are available with MDK:
 538
 539 * ``dev``: Changes a portion of Moodle settings to enable development mode
 540 * ``enrol``: Enrols users in any existing course
 541 * ``external_functions``: Refreshes the definitions of services and external functions
 542 * ``undev``: Reverts the changes made by ``dev``
 543 * ``users``: Creates a set of users
 544 * ``version``: Fixes downgrade version conflicts
 545 * ``webservices``: Does all the set up of webservices for you
 546
 547 License
 548 =======
 549
 550 Licensed under the `GNU GPL License <http://www.gnu.org/copyleft/gpl.html>`_