|Help developers to navigate|
|Table of Contents|
This page should help developers navigate who want to support Semantic MediaWiki development or develop extensions to SMW can use a number of resources to get started. Of course, it is strongly recommended to be familiar with the usage of SMW as well.
Moreover, there is an SMW architecture guide that provides a basic introduction to the main ideas and concepts in SMW from a developer perspective, which should be useful for reading and writing SMW-related code.
Hacking Semantic MediaWiki
This document should help newcomers and developers to navigate around Semantic MediaWiki and its development environment.
The main objective of the
Semantic MediaWiki software is to provide "semantic" functions on top of MediaWiki to enable machine-reading of wiki-content and allow structured content to be queried by means of different backends the software supports including:
Getting started ...
- Read this document
- Install git
@dev(with development happening against the master branch)
composer testlocally (see the test section) and verify that your installation and test environment are setup correctly so that you would find something like "OK, but incomplete, skipped, or risky tests! Tests ..." at the end as output (after the test run)
- Send a PR to the
Semantic MediaWikirepository to verify that your git works and you are able to replicate changes against the master branch
- Get yourself familiar with the Travis-CI and observe how a PR triggers CI jobs and review the output of those jobs (important when a job doesn't pass and you need to find the cause for a failure)
- You encountered some problems, create a ticket
The general policy of the
Semantic MediaWiki software and the development thereof is:
- No MediaWiki tables are modified or altered, any data that needs to be stored persistently is done using its own tables (writing to the cache is an exception)
- No MediaWiki classes are modified, patched, or otherwise changed
- Semantic MediaWiki tries to depend only on a selected pool of MediaWiki core classes (
Language... ) to minimize the potential for breakage during release changes
- Use publicly available
APIinterfaces to extend MediaWiki with Semantic MediaWiki functions
- Object interaction with MediaWiki objects should be done using accessors in the
Some simple rules that developers and the project tries to follow (of course there are exceptions or legacy cruft) is to create testable components where classes have a smaller footprint and come with a dedicated responsibility.
classhas a defined responsibility and boundary
- Dependency injection goes before inheritance, meaning that all objects used in a class should be injected.
- Instance creation (e.g.
new Foo( ... )) is delegated to a factory service
- A factory service should avoid using conditionals (
if ... then ...) to create an instance
- Instance creation and dependency injection are done using a service locator or dependency builder
- The top-level namespace is
SMWand each component should be placed in a namespace that represents the main responsibility of the component
PSR-4is used for resolving classes and namespaces in the
includesis the legacy folder that doesn't necessarily follow any of the policies or conventions mentioned in this document)
- Development happens against the master branch (see also the release process) and will be release according the the available release plan, backports should be cherry-picked and merged into the targeted branch
type hintingconsistently throughout a repository is vital to ensure class contracts can be appropriately followed
- Trying to follow
Single responsibility principleand applying
inversion of control(i.e dependency injection, factory pattern, service locator pattern) is a best practice approach
SemanticMediaWiki software alone deploys ~7000 tests (as of 16 March 2019) that are required to be passed before changes can be merged into the repository and are commonly divided into unit and integration tests.
- Read the introduction to the Semantic MediaWiki test environment and how to use
PHPUnitand how to write
- It is expected that each new class is covered by unit test and if the functionality spans into different components integration tests are provided as well to ensure the behaviour sought is actually observable and builds the base to define the behavioural boundaries.
Continues integration (CI)
The project uses Travis-CI to run its tests on different platforms with different services enabled to provide a wide range of environments including MySQL, SQLite, and Postgres.
Datamodelcontains the most essential architectural choice of Semantic MediaWiki for the management of its data including
Hacking by examples
- Creating annotations and storing data
- Querying data
- Writing a result printer
- Developing an extension
- Register a custom datatype
- Extending consistency checks on a property page
- Extending property annotators for a core predefined property, also the Semantic Extra Special Properties extension provides a development space for deploying other predefined (special) property annotations
- Contributing to Semantic MediaWiki
- Help:Writing testable code
- Help:Unit tests
- Integration tests
- MediaWiki resources for developers
Web applications with open user communities are specifically threatened by security vulnerabilities. SMW developers are responsible for taking specific care to avoid vulnerabilities of all kinds. Every developer should carefully read the MediaWiki security guidelines for developers.
For more information, please read security and software vulnerabilities.