Programmer's guide to SMW
Developers who want to support SMW 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.
All developers who want to contribute code to SMW should carefully read this page.
Contents |
[edit] Getting started
The SMW architecture guide provides a basic introduction to the main ideas and concepts in SMW from a developer perspective.
When switching from a user to a developer of SMW, you should also change the configuration of your testing wiki to ensure that you do not overlook possible errors or problems (especially those created by your own code). Please read about how to debug MediaWiki, in particular the section about PHP error reporting. All MediaWiki extensions are expected to run without issuing any PHP notices!
Also take a moment to familiarise yourself with the MediaWiki resources for developers.
[edit] Code documentation
SMW and its extensions try to provide thorough code documentation as part of their program files. An API documentation is automatically generated from this data:
This documentation encompasses SMW, Semantic Result Formats, Semantic Forms, Semantic Drilldown and Semantic Maps. It is rebuilt every day from the current contents of SVN. Further extensions can be added to this documentation if they relate to SMW, are hosted in MediaWiki SVN, and use naming conventions that prevent confusion with the other extensions (which use prefixes SMW, SRF, SF, SD and SM, respectively).
To get a quick overview of the code distribution in SMW, you can have a look at
[edit] Security aspects
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.
If vulnerabilities are discovered, special care is needed to minimize the risk of them being exploited. In particular, it is wise to first contact the core developers directly (e.g. send an email to Markus Krötzsch), to ensure that an updated version can be released before the bug is public. Also note that the project SVN is public and can be monitored by potential attackers. So commit messages like "Fixed critical security vulnerability" can also be problematic. For more information on handling security problems in open source software, see [1].
[edit] Committing code or patches to SVN
Anyone who commits code to SVN has a special responsibility to check that the guidelines on this page are met, whether or not he was the one who wrote the code in the first place. Check that the following has been done before committing code:
- The code has been read by the committer, and it was found to be readable and understandable.
- The committer has verified that the code is secure. Especially, it was checked that no user-entered data is ever used in HTML or in SQL without being escaped properly (see MediaWiki security guidelines above).
- The committer has tested the code to see if it really does work as expected. Each feature or bugfix that is essential for making the code useful must have been checked for at least one example. If the code includes configuration options, then it also must be tested that they work correctly.
Again: All code must be read and tested by the person committing it to SVN. These tasks can also be distributed among several SMW developers who have commit permissions, but ultimate responsibility is always with the person who does the commit. This is especially important for code coming from contributions via Bugzilla or email. Code from such sources must be considered as unreviewed and untested. Of course, if the contributor is experienced, then the code will be in such a readable and well-documented shape that the remaining work on the side of the committer is very little. Contributors should be pointed to this page to improve their code so that they can speed up the processing of their contribution.
[edit] Improving your programming/testing environment
It is useful to setup the local wiki installation in a way that helps to detect and track down problems quickly. On the one hand, it is useful to use not-so-common installation settings to ensure that they are tested at some point:
- Use a non-empty DB table prefix when installing MediaWiki.
- Use $wgArticlePath = "$wgScript?title=$1"; in your LocalSettings.php (CGI compatibility mode). You may also change this back and forth to test both styles of URIs with your code.
- In addition, enable $wgShowSQLErrors = true; and $wgDebugDumpSql = true; in your LocalSettings.php.
On the other hand, some PHP-specific settings are useful for find code problems:
- The required version of PHP is found in INSTALL.
- All developers need to have all errors, warnings, and notices in PHP switched on. Edit your file php.ini to contain error_reporting = E_ALL and remove any other statement of this kind.
- Edit your php.ini to contain allow_call_time_pass_reference = Off.
- Your final code should never create any of the respective messages.
- Enabling xdebug for your PHP improves the detail of the bug reports (the actual profiling feature of xdebug does not need to be enabled for this).
[edit] Programming style
SMW and many of its extensions stick to strict naming conventions and code styles based on the MediaWiki coding conventions. The following guidelines apply to SMW, but can often be adopted to other extensions by just changing the prefix SMW.
[edit] Files and folders
- Files in the project are all prefixed with "SMW_". In general, it should be possible to put all the project files into MediaWiki's include folder without getting name conflicts.
- Folders are usually not changed or created. The only exception are Special pages which all reside in their own folders below the folder "specials".
[edit] Encoding
- All files need to be stored as UTF8! This is absolutely crucial.
- All line endings must be UNIX-style. Set your auto-props!
[edit] PHP
- Do not use a closing "?>" tag in your source files. It is a source for errors that is not needed in included files.
[edit] Naming conventions
In general, all names are written CamelCase, although methodNames and variableNames typically start with lower case letters.
- Classes are prefixed with "SMW" if they are accessible globally. Class definitions that are encapsulated in methods do not have a prefix. Another exception are classes for Specials which should be named after the special, as is common in MediaWiki.
- Functions are prefixed with "smwf" if they are accessible globally. Class functions do not have a special prefix.
- Variables are prefixed with "smwg" if declared globally. Variables in a class do not have a special prefix. Local variables in functions typically do not CamelCase, but use "_" if any separation is needed.
- Constants are written ALL_CAPS with underscores as internal separator, and are to be prefixed with "SMW_", as e.g. in "define('SMW_SP_HAS_TYPE', 1)".
[edit] Code layout and indenting
In general, code layout is guided by the MediaWiki coding conventions. Please be sure to read this document.
- Document all your code (see below for details)!
- Avoid single lines of code becoming too long.
- Indenting of program blocks is done with tabulators, not with spaces. All program blocks are indented.
- All indented program blocks should be enclosed with { and }, even if they have one line only.
- Using in-line conditionals for value computations is fine ("condition?thenvalue:elsevalue").
- Spaces around "=" (variable assignment) and all operators, including "." (string concatenation), are recommended.
- In conditionals, conjunctions and disjunctions should be written as && and ||, respectively, not as and and or.
- Value constants like true, false, and null are always written lower case.
- Class-members should be declared protected or private if applicable. The use of public is not required, since it is the default (other than for variables, where public is to be preferred over var).
- Use the keyword static where appropriate. Consider changing global functions into static class functions.
- When you finish some task, take some time to remove unused debug-statements, functions, and local variables from your code!
[edit] JavaScript
[edit] Naming conventions
In general, all names are written CamelCase, although methodNames and variableNames typically start with lower case letters.
- Functions are prefixed with "smw_".
- Variables mostly don't adhere to any naming conventions, but global variables should have the prefix "smw_".
[edit] Code layout and indenting
No general code layout for SMW's JavaScript has been proposed or implemented yet.
[edit] Documentation
The SVN-version must be deployable at 90% of the time. Update INSTALL whenever needed! Provide update instructions and methods in case of incompatible changes.
- Every class and function must have a short documentation, enclosed in "/** ... */". These blocks are used to generate the MediaWiki code documenation via doxygen.
- Use @since possible to indicate the version in which the function or field was added. Also do this for hooks.
- Use type hinting where possible. It is important to do this in new code that can be inherited, as deriving classes won't be able to use type hinting when this is not done in the base class.
- Use "@todo" and "@bug" in doxygen comments to keep track of to-dos and bugs directly within the code.
- Complex code and hacks should be documented with C-style line-comments ("// ...").
- User documentation (mostly for SMW_Settings.php) should be documented with Shell-style line-comments ("# ...").
- Implementations that affect usage must be documented in the online user documentation before release.
- Changes that are relevant to users, administrators, or third-party developers must be mentioned in the file RELEASE-NOTES. A short note is enough.
[edit] Creating result formats
See this page on how to create result formats.
[edit] Getting support
The SMW Project welcomes all potential contributors and extension developers. Developers can discuss on the SMW developer mailing list, which can also be used to contact the SMW core developers. The SMW Project welcomes bug reports via MediaZilla, which can also be used for feature requests.
Commercial support, custom development projects, and trainings may also be available (depending on your physical location and project specifications) – please contact Markus Krötzsch for further information.
[edit] Testing
[edit] SMW System Testing
- General Information: SMW System Testing with Selenium
[edit] SMW Unit Testing
- No guidelines, yet. Still, highly recommended for high-quality code (e.g., PHPUnit).
