Sandscape Development

From Arcmage Wiki
Jump to: navigation, search

Development Process

The project is being developed in accordance to eXtreme Programming rules[1]. We divide the all development in small iterations, that will focus on small sets of features, accompanied by several tests and experimentation called spike solutions. Some iterations will focus only on spike solutions, others on correcting bugs or joining previously created spike solutions.

Documentation is important, the "well written code is it's own documentation" motto doesn't apply in this project. There will be comments in code, design documents describing the chosen course, feature list and every point that may cause any doubts for any new developer. But documentation is not only for those that are new to the project, it is usual that the programmer that writes some piece of code will forget the details of he/she wrote after a few weeks or months.

Tools & Technologies

The Sandscape design document suggested some tools to be used in the development of Sandscape, some will be followed, some may be changed. Currently the developer working on the project uses the following list of tools, all of them multi-platform:

  • NetBeans IDE[2] as the main editor. XHTML, CSS, JS, PHP and SQL files are all created in NetBeans IDE using UTF-8 encoding.
  • Dia[3] for creating diagrams, like the ER Diagram in the database folder. All diagrams will be exported to PNG format, but the source is edited using Dia.
  • AsciiDoc[4] for documentation.
  • GIMP for any image editing.
  • Git for source code control and general file revision.
  • Apache Web Server

Though the above list shows what tools are being used, you can use any other tool you like if you want to collaborate in the project, the only requirement is that the files produced by any software you use are in an open format, or one that can be easily opened using open source software in any platform. This requirement excludes things like Photoshop for image editing or MS Word for documents, even if .DOC files are used, but allows other formats like PDF. As a rule of thumb: if the file you've used can't be opened by open source software without information loss don't use it.

The following technologies are used:

  • jQuery to deal with all JS related stuff (bundled with Yii).
  • jQueryUI for any effects and extra interaction (bundled with Yii).
  • PHP 5. We aim for PHP 5.3.
  • Yii framework
  • MySQL 5.0 minimum, though the current SQL code will run correctly in previous versions we use foreign key constraints that will be ignored in versions below 5.0. The project is not created to be database independent.
  • Blueprint CSS framework (bundled with Yii).

Other technologies may be added at a latter stage, if they're found necessary. Current used technologies may change.

Sandscape uses SourceForge [5] and the Trac[6] system provided there for general issue management and feature requests.

Setting up Sandscape contains the bare instructions to setup Sandscape for both usage and development.

Git Repository

To get the latest files you'll need to access the Git repository. Accessing the Git repository means cloning the complete repository into your computer, the process may take some time depending on your connection speed.

You can have a read-only copy by issuing the following command:

git clone git:// sandscape

To have write permissions please contact the lead developer using SourceForge contact system [7]. You need to be registered in SourceForge, also necessary to have write access to the main repository.

Tutorials about Git

  • Introductory tutorial [8]
  • Crash course for SVN users [9]

Code/Development Conventions

Code conventions are nothing more than rules about the way the code is written and the project files are organized. These rules make it easier for the involved developers to collaborate and share code, please make sure you respect them, even if you don't agree with them, make an effort to follow them.

The rules we follow are those create by Sun Microsystems, now part of Oracle Corporation, for the Java programming language. You can find the HTML version here. The rule text may be too long to read but if you're not familiar with such rules, please take some time to understand them, if you're confortable with code you may find it easier to understand the rules by just looking at it.

As a simple introduction, we use:

  • CamelCase, both in PHP code and in database. Yes, our database tables and fields use CamelCase.
  • Curly braces are opened in the same line as the function name, class name or block (if, else, for, foreach, while, ...) and are closed aligned with the start of the code block in a new line.
  • Use 4 spaces, never tabs.
  • Comments are written using appropriate tags and placed above the function name or class name. Make sure you place a @return tag with the correct return type (never use object, always use the exact returned class).
  • When a function parameter is suppose to be an object and you know what type of object it is, declare the correct type.
  • Don't use underscores.
  • All styling should be done in CSS files.
  • Write proper commit messages if you have access to the repository hosted at SourceForge.

Issues from Trac

All issues should be posted on our issue software and we should try to implement features that are found there before anything else, nonetheless, issue tracking is used for just that: keep track of issues. So, when looking at the issues or when creating a new issue keep the following ideas in mind:

  • Issues can be created with any priority, component, version or other information, unless they have been accepted, none of those settings will matter. Any issue marked as new can have it's settings changed to any other value.
  • Issues that have been accepted should be properly configured when they are marked as 'accepted. The only exception to this is the milestone setting, this one should be set when we have the exact milestone for the issue.
  • Sometimes, lower priority issues may be picked before higher priority ones at the choice of the develoer that will work on the issue.


Our roadmap is based on XP iterations, at the end of each iteration the project will have a set of new features or bug corrections. Given that there is only one developer currently working on the project, iterations will not have the usual one to two weeks length but will expand closely to one or one and a half months, hopefully not more.

As a way to keep control of what iterations exist, they will be named, using an existing card's name in the Gaia faction. The use of these names is merely a convenience. They allow us to have named iterations that are not based on dates or version numbers.

Since our Trac was setup we started using it to manage the list of tasks and iteration names (their called milestones in Trac), you can access our current roadmap there. We maintain all the iteration reports and documentation here.

Iteration Reports

Iteration reports were previously available at this wiki but they were moved to the source repository. You will find them at the _dev/docs/reports directory as text files written using Asciidoc.

List of iterations:

  • Completed:
    • Elvish Scout
    • Sudden Growth, v1.0
    • Green Shield, v1.1
  • Running:
    • Elvish Shaman, v1.2
  • Future:
  • Soulharvester
  • Serenity