| Index: trunk/extensions/Wikidata/POLICY |
| — | — | @@ -0,0 +1,90 @@ |
| | 2 | +This is a document describing some policies and conventions regarding |
| | 3 | +the Wikidata codebase. |
| | 4 | + |
| | 5 | +== SVN == |
| | 6 | + |
| | 7 | +We use the version control repository also used by many other |
| | 8 | +MediaWiki extensions. |
| | 9 | + |
| | 10 | +- The Wikidata branch contains modifications to the MediaWiki |
| | 11 | + core that are necessary to run Wikidata. (These should |
| | 12 | + become part of the SVN trunk eventually.) |
| | 13 | +- The trunk/extensions/Wikidata folder contains the actual |
| | 14 | + extension. This _is_ SVN trunk; do not get confused between |
| | 15 | + the two. You need both. |
| | 16 | + |
| | 17 | +Code is integrated on omegawiki.org on a milestone basis; |
| | 18 | +integration should happen ASAP if there are database changes, so |
| | 19 | +that people downloading an omegawiki.org dump can use it with |
| | 20 | +the latest code. |
| | 21 | + |
| | 22 | +If you intend to commit potentially broken code, make sure that you |
| | 23 | +communicate with the core dev-team upfront! Otherwise, test your code |
| | 24 | +before committing to avoid unexpected breakage in live sites. |
| | 25 | + |
| | 26 | +Make sure your SVN client is configured to auto-convert line endings: |
| | 27 | +http://www.mediawiki.org/wiki/Subversion/auto-props |
| | 28 | + |
| | 29 | +== Releases == |
| | 30 | + |
| | 31 | +There are currently no releases of OmegaWiki beyond the latest version in |
| | 32 | +SVN; the basic conditions for an official 1.0 release should be: |
| | 33 | +- the code is in full compliance with this policy |
| | 34 | +- the code does not depend on any idiosyncratic changes to the MW core |
| | 35 | +- Wikidata is installable from scratch in a straightforward fashion, |
| | 36 | + including DB setup. |
| | 37 | + |
| | 38 | +== Database changes == |
| | 39 | + |
| | 40 | +When making a change to the database schema, always make sure to add the |
| | 41 | +respective script to Database scripts/Incremental, following the example of |
| | 42 | +the existing scripts (do not forget to insert a row into the script_log |
| | 43 | +explaining the change). |
| | 44 | + |
| | 45 | +== Documentation == |
| | 46 | + |
| | 47 | +Every class and method should have a PHPDoc compliant documentation |
| | 48 | +header. See MediaWiki's includes/Namespace.php for an example of |
| | 49 | +a fully documented class. It's OK not to document getters and |
| | 50 | +setters and 1-2 line functions. |
| | 51 | + |
| | 52 | +Code without proper documentation may be refused. |
| | 53 | + |
| | 54 | +== Directories == |
| | 55 | + |
| | 56 | +See README for an overview of the directory structure. Do not add new |
| | 57 | +directories unless needed. :-) |
| | 58 | + |
| | 59 | +== Filenames == |
| | 60 | + |
| | 61 | +Filenames should be in CamelCase and, if possible, match the |
| | 62 | +contained class name. |
| | 63 | + |
| | 64 | +== Classes == |
| | 65 | + |
| | 66 | +Other than initial hook functions and command-line scripts, all |
| | 67 | +functions should exist in a class context. |
| | 68 | + |
| | 69 | +== Variables == |
| | 70 | + |
| | 71 | +Variable names are generally written in CamelCase (lower case first |
| | 72 | +letter), not containing underscores. |
| | 73 | + |
| | 74 | +== Globals == |
| | 75 | + |
| | 76 | +We should strive to reduce the number of globals where possible, |
| | 77 | +as they generally lead to bad design decisions and are intrinsically |
| | 78 | +dangerous (global read/write access). |
| | 79 | + |
| | 80 | +If you _must_ use a global, its name should begin with a $wd prefix. |
| | 81 | +This is to distinguish our globals from MediaWiki globals, which begin |
| | 82 | +with $wg. |
| | 83 | + |
| | 84 | +== Refactoring == |
| | 85 | + |
| | 86 | +Eliminate code which is never used; if you have plans for it and want to |
| | 87 | +commit it to share it, do so in a separate directory from the main code (e.g. |
| | 88 | +a "workspace/" subdirectory). Better yet, commit in a separate branch. |
| | 89 | + |
| | 90 | +Remove redundant code and make sure that your code remains understandable |
| | 91 | +even if all comments were removed. |
| \ No newline at end of file |