Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
224 lines (155 loc) · 6.5 KB

DEVELOPMENT.md

File metadata and controls

224 lines (155 loc) · 6.5 KB
Raw

Development environment

Set up a local development environment for Semantic MediaWiki (SMW) using Docker. The environment is powered by docker-compose-ci (included as a Git submodule in build/) and mirrors the GitHub Actions CI pipeline — tests that pass locally will pass in CI.

Prerequisites

Quick start

git clone --recurse-submodules https://github.com/SemanticMediaWiki/SemanticMediaWiki.git
cd SemanticMediaWiki
make install

This builds the Docker containers, installs MediaWiki (MW 1.43, PHP 8.1, MariaDB 11.2 by default), and runs composer update inside the extension.

Verify the setup:

make composer-test

This runs lint, PHPCS, and all PHPUnit test suites — the same sequence as CI.

Browsing the wiki

make install does not expose any ports by default. To access the wiki in a browser, create a compose override file and reinstall:

cat > build/docker-compose.override.yml <<'EOF'
services:
  wiki:
    ports:
      - 8080:8080
EOF
make destroy install

The wiki is then available at http://localhost:8080 (credentials: WikiSysop / wiki4everyone). The override file only needs to be created once.

Seeding demo data

The dev wiki starts empty. To populate it with sample pages that exercise SMW features, run the seeder script:

docker exec semanticmediawiki-mysql-wiki-1 php /var/www/html/maintenance/run.php \
  SemanticMediaWiki:seedDemoData --force

This creates ~147 pages tracked in Category:Seed data. To remove them:

docker exec semanticmediawiki-mysql-wiki-1 php /var/www/html/maintenance/run.php \
  SemanticMediaWiki:seedDemoData --force --clear-only

Syncing local changes

By default, the extension is copied into the container at build time and local edits are not reflected automatically. For active development, add a bind mount so changes sync instantly in both directions.

Bind mount (recommended)

Add a volumes entry to your build/docker-compose.override.yml:

services:
  wiki:
    ports:
      - 8080:8080
    volumes:
      - ../:/var/www/html/extensions/SemanticMediaWiki

Then rebuild:

make destroy install

With the bind mount, edits on the host are immediately visible in the container and vice versa — no copying needed. Auto-formatters like composer fix write directly to your working tree.

Note: The bind mount overlays the copy that was baked into the image at build time. The container's vendor/ directory comes from your host, so run composer update inside the container if dependencies are missing:

docker exec semanticmediawiki-mysql-wiki-1 bash -c \
  "cd /var/www/html/extensions/SemanticMediaWiki && composer update"

Manual copy (without bind mount)

If you prefer not to bind-mount (e.g., to test against the exact image that CI builds), copy files in and out manually:

# Copy a local file into the container
docker cp path/to/file.php \
  semanticmediawiki-mysql-wiki-1:/var/www/html/extensions/SemanticMediaWiki/path/to/file.php

# Copy a file back from the container
docker cp semanticmediawiki-mysql-wiki-1:/var/www/html/extensions/SemanticMediaWiki/path/to/file.php \
  path/to/file.php

Configuration

The Makefile accepts these variables:

Variable Default Description
MW_VERSION 1.43 MediaWiki version
PHP_VERSION 8.1 PHP version
DB_TYPE mysql Database type
DB_IMAGE mariadb:11.2 Database Docker image

Override on the command line or in a .env file at the project root:

# Command line
make install MW_VERSION=1.44 PHP_VERSION=8.3

# Or via .env file
echo 'MW_VERSION=1.44' >> .env
echo 'PHP_VERSION=8.3' >> .env
make install

To switch versions, destroy and reinstall:

make destroy install MW_VERSION=1.45 PHP_VERSION=8.4 DB_IMAGE="mariadb:11.8"

Running tests

Inside the container

From a shell inside the container (make bash), run tests directly:

cd /var/www/html/extensions/SemanticMediaWiki

# Full test suite (lint + PHPCS + PHPUnit)
composer test

# Unit tests only
composer phpunit:unit

# Integration tests only
composer phpunit:integration

Via Make

# Full test suite (lint + PHPCS + PHPUnit)
make composer-test

# Unit tests only
make composer-test COMPOSER_PARAMS="-- --testsuite=semantic-mediawiki-unit"

Via docker exec

To run individual test suites or classes from your host machine (the container name follows the pattern semanticmediawiki-<DB_TYPE>-wiki-1):

# Unit tests
docker exec semanticmediawiki-mysql-wiki-1 bash -c \
  "cd /var/www/html/extensions/SemanticMediaWiki && composer phpunit:unit -- --no-coverage"

# Integration tests
docker exec semanticmediawiki-mysql-wiki-1 bash -c \
  "cd /var/www/html/extensions/SemanticMediaWiki && composer phpunit:integration -- --no-coverage"

# Single test class
docker exec semanticmediawiki-mysql-wiki-1 bash -c \
  "cd /var/www/html/extensions/SemanticMediaWiki && composer phpunit -- --no-coverage --filter 'TestClassName'"

PHPCS

Run analysis (lint + code style):

docker exec semanticmediawiki-mysql-wiki-1 bash -c \
  "cd /var/www/html/extensions/SemanticMediaWiki && composer analyze"

Auto-fix code style violations:

docker exec semanticmediawiki-mysql-wiki-1 bash -c \
  "cd /var/www/html/extensions/SemanticMediaWiki && composer fix"

If you're not using a bind mount, remember to copy fixed files back to your local checkout after running composer fix.

Caution: composer analyze exits 0 even with warnings. Read the full output — warnings must also be fixed.

Interactive shell

make bash
# or:
docker exec -it semanticmediawiki-mysql-wiki-1 bash

CI

CI runs on GitHub Actions using the same Docker and Makefile setup. The workflow is defined in .github/workflows/main.yml.

Test matrix

MediaWiki PHP Database Status
1.43 8.2 MariaDB 11.2 Stable (+ coverage)
1.43 8.3 MariaDB 11.2 Stable
1.44 8.3 MariaDB 11.2 Experimental
1.44 8.3 MariaDB 11.8 Experimental
1.45 8.4 MariaDB 11.8 Experimental

CI runs make ci, which calls make install followed by composer test and npm test.