Contributing to Semantic MediaWiki
Types of contributions
There are different ways to make a contribution to Semantic MediaWiki (SMW) while a few guidelines are necessary to keep the workflow and review process most efficient.
A bug is the occurrence of an unintended or unanticipated behaviour that causes a vulnerability or fatal error.
- You may help us by reporting bugs via the issue tracker. See the help page on reporting bugs (environment, reproducing) as well as on identifying bugs (stack-trace) for information on how to do this best. Please remember to always provide information about your environment as well as a stack-trace.
- You may help us to do pre-release testing by joining the team of testers on GitHub.
A feature request is a new, or altered behaviour of an existing functionality. You may describe them via the issue tracker.
A request should contain a detailed description of the expected behaviour in order to avoid misconceptions in the process of an implementation. The following notes are provided to aid the process and help prioritize a request for project members.
- Why is the feature requested or relevant?
- What does the feature solve? (e.g. it addresses a generalizable behaviour, it solves a specific use case etc.)
- Examples demonstrate the expected behaviour by:
- Being simple, clear, and targeted towards the feature and not rely on any other external functionality (such as other parser functions or extensions).
- In case of a modified behaviour, examples demonstrate the old and new behaviour together with an explanation of the expected difference
- In case of a new behaviour, examples are written down to outline the expected new behaviour (best practice is a step-by-step description) together with a use case
- Examples made available via the sandbox.
- Examples should be adaptable so they can be used as part of an integration test.
Documenting the software is an important part of the work to make the software usable. You may help us by creating, updating or amending the documentation of the software on Semantic-MediaWiki.org.
- You may help us by providing software translations via translatewiki.net. See their progress-statistics to find out if there is still work to do for your language.
- You may also help up provide translations for important pages on the Semantic MediaWiki homepage. See the info page for further information
You may help us by providing patches or additional features via a pull request but in order to swiftly co-ordinate your code contribution, the following should suffice:
- Please ensure that pull requests are based on the current master. See also the developer documentation overview for further information.
- Code should be easily readable (see NPath complexity,
if elsenesting etc.) and if necessary be put into separate components (or classes)
- Newly added features should not alter existing tests but instead provide additional test coverage to verify the expected new behaviour. For a description on how to write and run PHPUnit test, please consult the manual.
Thank you for contributing to Semantic MediaWiki!
Committing code or patches
Anyone who commits code to the CM System 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. 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.
Other repository links can be found at the respective module/extension help page.