Software Systems

This document presents informations about development practices used by Aplikacja.info. Detailed instructions about every project are always stored with project documentation (under doc/ subdirectory).

1. The Software

This section shows software used for our projects.

Operating systems

We are mainly working on Linux distributions. Currently used distributions:

Formats

Primary documentation format is HTML (optionally connected with CmsWiki). Important benefits:

  • simple
  • known by web applications developers
  • portable (scales well from full-featured web browsers to simple handhelds)

Alternate documentation format is RST (ReStructuredText). Important benefits:

  • simple like ASCII documents (minimal markup)
  • easy embedding of software code listings
  • easy convertable to other formats

Accepted variation of RST is use of Wiki. Benefits of this option:

  • document can be developed and inspected on-line (possibly in real-time with customer)
  • it's very easy to add changes (no need to update/checkin cycle to version control system)

For documenting software interfaces it's best to use automatically generated from source docs (Java Doc for Java, PyDoc for Python)

Version control software

Main version control software used for Aplikacja.info projects are GIT/Bazaar. Important benefits:

  • Allows for repeatedly merging from branch to trunk
  • Allows for fully disconnected operations (they are distributed versioning systems)

Alternate version control system can be used when 3rd party work will be integrated into project (for example custom graphics done on Windows): SVN. Important benefits:

  • many client software for different environments
  • atomic commits identified by revision number
  • some operations are off-line (fast)

Local branches can be managed using separate script called PMS. Some old projects still use CVS, but we plan migrations into distributed systems.

2. Development process

In this section we describe how software is integrated into our work (process = usage of tools).

Version control scripts

In order to standardise version control usage main control script (Makefile, build.xml) supports the following commands:

  • ci: runs all registered tests and commits to current branch/trunk
  • sync: does update from remote repository of current branch/trunk, then does push operation (for distributed VCS-es)
  • up: does update from remote repository
  • bcreate: creates public branch and switches to it
  • bmerge: merges a branch to current branch then deletes merged branch
  • sb: switches to selected branch
  • bimport: downloads branch from a remote repository by a name (operation called by reviewer or integration programmer)
  • di: shows current local diff file (to inspect local changes)
  • st: shows status of local working copy
  • pimport: downloads patch from a remote repository by a name (operation called by reviewer or integration programmer)
  • pexport: export all locally registered patches to remote repository (operation called by developer using PMS to manage task)

Integration with code review

High-risk tasks are integrated using peer code review process based on VCS functionality.

  • task done on a branch / PMS patch
  • code review by another developer
  • optional fixes done by original developer (possibly with another developer assistance)
  • integration to trunk
  • install

On-line code review / tasks

By Online I mean: code review inside trunk/master. We used to place TODO's in code that looks something like this:

   TODO:ABC: Refactor method X because it's too large, add
   test to improve coverage of this module to 90% -- DCI

Where: ABC is recipient of this note, DCI is an author. ABC during fix removes the TODO from code and commits this change in one commit (so change is wisible together with removed comment in history).

Unit tests

Coverage of a source code with unit tests is the most important activity that ensure good shape of a project. We use the following unit testing libraries:

and the following coverage analysis tools:

Unit testing process in tightly integrated into standard development scripts (Makefile, build.xml). Running of all unit tests succesffully is a precondition to succesfull commit into version control system.

Specification tagging

It's an activity you (a programmer) can ensure that whole specification is covered in source code. Rules:

  • A programmer inserts into specification unique tags in form: [DCI001] (where: DCI is programmer signature, 001 is tag number)
  • Such tag is places (possibly in many places) in source code / technical documents
  • One can search for tag occurences in specification / source code

Tags in specification will show which features are complete (and we can measure progress then). It's very easy to inspect code by give feature: simple search for tag attached to signature in source code.

Static analysis

Static analysis is a method used to catch inconsistencies between project resources (source code, HTML templates, XML configuration, other files in project etc.). Simplest form of inconsistency is to use undefined attribute of a form bean in JSP. Such inconsistency will cause an error in runtime and of course could be detected by extensive testing, but:

  • manual testing is expensive - takes long time to manual "reclick" all application
  • manual testing is expensive - must be redone after every changeset to prevent regression (no one knows which parts are broken after change)
  • manual testing is expensive - it's very hard to reproduce some errors, special state must be set in database

Many defects that are causing errors during testing could be easily detected by dedicated parsers that scan source code and check if defined rules hold. A special scaner is written and connected to base unit testing suite to detect as many as possible errant cases at unit-testing time. Benefits:

  • fasssst: all resources are checked in seconds
  • checks are cheap - can be redone every few minutes by every developer to prevent regression

We applited static analysis for the following technologies:

  • JSF + form beans
  • Struts + form beans + Hibernate
  • TAL (Zope) + Python objects
  • Eclipse manifest + jar files
  • Velocity HQL templates + Java Beans (Hibernate)
  • Django templates + django views / ORM objects

3. Delivery

We are delivering very often, very early. A customer can see project progress based on frequent releases installed in real-time on test machines. By using stable trunk policy guarded by unit tests we can make such deliveries stable.