This is a document describing some policies and conventions regarding
the Wikidata codebase.

== SVN ==

We use the version control repository also used by many other
MediaWiki extensions.

- The Wikidata branch contains modifications to the MediaWiki
  core that are necessary to run Wikidata. (These should
  become part of the SVN trunk eventually.)
- The trunk/extensions/Wikidata folder contains the actual
  extension. This _is_ SVN trunk; do not get confused between
  the two. You need both.

Code is integrated on omegawiki.org on a milestone basis; 
integration should happen ASAP if there are database changes, so
that people downloading an omegawiki.org dump can use it with
the latest code.

If you intend to commit potentially broken code, make sure that you
communicate with the core dev-team upfront! Otherwise, test your code 
before committing to avoid unexpected breakage in live sites.

Make sure your SVN client is configured to auto-convert line endings:
http://www.mediawiki.org/wiki/Subversion/auto-props

== Releases ==

There are currently no releases of OmegaWiki beyond the latest version in
SVN; the basic conditions for an official 1.0 release should be:
- the code is in full compliance with this policy
- the code does not depend on any idiosyncratic changes to the MW core
- Wikidata is installable from scratch in a straightforward fashion,
  including DB setup.

== Database changes ==

When making a change to the database schema, always make sure to add the
respective script to Database scripts/Incremental, following the example of
the existing scripts (do not forget to insert a row into the script_log
explaining the change).

== Documentation ==

Every class and method should have a PHPDoc compliant documentation
header. See MediaWiki's includes/Namespace.php for an example of
a fully documented class. It's OK not to document getters and
setters and 1-2 line functions.

Code without proper documentation may be refused.

== Directories ==

See README for an overview of the directory structure. Do not add new
directories unless needed. :-)

== Filenames ==

Filenames should be in CamelCase and, if possible, match the
contained class name. 

== Classes ==

Other than initial hook functions and command-line scripts, all 
functions should exist in a class context.

== Function parameters ==

Add type hints and default values where appropriate.

== Variables ==

Variable names are generally written in CamelCase (lower case first
letter), not containing underscores.

== Globals ==

We should strive to reduce the number of globals where possible,
as they generally lead to bad design decisions and are intrinsically 
dangerous (global read/write access).

If you _must_ use a global, its name should begin with a $wd prefix. 
This is to distinguish our globals from MediaWiki globals, which begin 
with $wg.

== Refactoring ==

Eliminate code which is never used; if you have plans for it and want to
commit it to share it, do so in a separate directory from the main code (e.g.
a "workspace/" subdirectory). Better yet, commit in a separate branch.

Remove redundant code and make sure that your code remains understandable
even if all comments were removed.