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