Information for developers

Alaveteli is an open source project. Full-time mySociety developers together with devs from all around the world actively contribute to the codebase. These notes and links will help you if you want to help too.

  • The software is written in Ruby on Rails 4.x. We support postgresql as the backend database. A configured mail transfer agent (MTA) like exim, postfix or sendmail is necessary to parse incoming emails. We have production sites deployed on Debian (Wheezy) and Ubuntu (14.04 LTS). For performance reasons, we recommend the use of Varnish.

  • To help you understand what the code is doing, read this high-level overview, which includes a diagram of the models and how they are related.

  • See the API documentation for how to get data into or out of Alaveteli.

  • If you need to change or add strings in the interface, see our guidelines for internationalisation, which include notes about our use of gettext.

  • We use the git flow branching model, the latest development version is always found on the develop branch. The latest stable version is always on the master branch. If you plan to collaborate on the software, you may find the git flow extensions useful.

  • Installing the software is a little involved, though it’s getting easier. If you stick to Debian or Ubuntu, it should be possible to get a running version within a few hours. If you’ve got your own server, run the installation script, or follow the instructions for a manual installation. Get in touch for help.

  • A standard initial step for customising your deployment is writing a theme. If you only read one thing, it should be this!

  • Like many Ruby on Rails sites, the software is not hugely performant (see these notes about performance issues gathered over time with WhatDoTheyKnow). The site will run on a server with 512MB RAM but at least 2GB is recommended. Deployment behind Varnish is also fairly essential. See production server best practices for more.

  • There’s a number of proposals for enhancements, such as more user-focused features, but see also…

  • …the github issues. We mark issues with the label suitable for volunteers if we think they are especially suitable for diving into if you’re just looking for something relatively small to get your teeth into.

  • We try to ensure every commit has a corresponding issue in the issue tracker. This makes changelogs easier as we can gather all the fixes for a particular release against a milestone in the issue tracker, like this 0.4 release.

  • If you’re experiencing memory issues, this blog post about some strategies used in the past might be useful.

  • If you’re coding on a mac, see these MacOS X installation notes.

  • We try to adhere to similar good practice across all our projects: see mysociety.github.io for things like our coding standards