Glossary of terms for Alaveteli, mySociety's freedom of information
platform.
Definitions
-----------
-
Alaveteli
-
Alaveteli is the name of the open source software platform created
by mySociety for submitting,
managing and archiving Freedom of Information requests.
It grew from the successful FOI UK project
WhatDoTheyKnow.
We use the name Alaveteli to distinguish the software
that runs the platform from any specific website that it is powering.
-
asker agnostic
-
Freedom of Information (FoI) law typically considers
the responses given by the
authorities to be asker agnostic. This means
that the reply should not be any different depending on who asked for the
information. One consequence of this is that the response
can be published, because in theory everyone
could ask for it and expect, by law, to receive the same information.
Despite this, it's still very common all around the world for authorities to reply
to FoI requests privately, instead of publishing their responses themselves. One of the
functions of Alaveteli is, therefore, to act as a public repository of published answers.
This also serves to reduce duplicate requests, by publishing the answer instead of
requiring it to be asked again.
-
authority
-
An authority is the term we use for any of the bodies, organisations,
departments, or companies to which users can send requests.
More information:
-
An administrator can add, edit, or remove authorities in the admin
-
Authorities are usually, but not always, public bodies that are obliged by the local
Freedom of Information (FoI) law to respond. Sometimes an
Alaveteli site is set up in a jurisdiction that does not yet have FoI law. In the UK,
we add some authorites to our WhaDoTheyKnow
site that are not subject to FoI law, but which have either voluntarily submitted themselves
to it, or which we believe should be accountable in this way.
-
black hole
-
A black hole is an email address that accepts and destroys
any email messages that are sent to it. Alaveteli uses this for "do not
reply" emails, which are usually automatically generated system emails.
More information:
-
Use the config setting
BLACKHOLE_PREFIX
to specify what this email address looks like.
-
Conversely, see
CONTACT_EMAIL
to specify the email address to which users' emails (such as support
enquiries) will be delivered.
-
Capistrano
-
Capistrano is a remote server automation and deployment tool written in Ruby.
Alaveteli's deployment mechanism, which is optional, uses it.
-
censor rule
-
Alaveteli administrators can define censor rules to define
which parts of replies or responses should be
redacted.
More information:
-
see the
admin manual
for more about censor rules
-
censor rules may simply redact text that exactly matches a
particular sentence or phrase, or may use
regular expressions
-
development site (also: dev, development server)
-
A dev server is one that is running your Alaveteli site
so you can customise it, experiment
with different settings, and test that it does what you expect.
This is different from a
production server, which is the one your
users actually visit running with live data, or a
staging server,
which is used for testing code before it goes live.
On your dev server, you should set
STAGING_SITE
to 1.
-
Freedom of Information (also FOI)
-
Freedom of information laws allow access by the general public
to data held by national governments. They establish a "right-to-know"
legal process by which requests may be made for government-held
information, to be received freely or at minimal cost, barring standard
exceptions.
[from wikipedia]
-
git (also github, git repository, and git repo)
-
We use a popular source code control system called git. This
helps us track changes to the code, and also makes it easy for other people
to duplicate and even contribute to our software.
The website github.com is a central, public
place where we make our software available. Because it's Open Source, you can
inspect the code there (Alaveteli is mostly written in the programming language
Ruby), report bugs, suggest features and many other useful things.
The entire set of files that form the Alaveteli platform is called the
git repository or repo. When you
install Alaveteli, you are effectively cloning our repository on your
own machine.
-
holding pen
-
The holding pen is the conceptual place where responses that
could not be delivered are held. They need attention from a administrator.
More information:
-
see the admin manual for
information on dealing with emails in the holding pen
-
MTA (Mail Transfer Agent)
-
A Mail Tranfer Agent is the the program which actually sends
and receives email. Alaveteli sends email on behalf of its users, and processes
the responses and replies it receives.
All this email goes through the MTA, which is a seperate service on your system.
More information:
-
see these instructions for configuring your MTA
(examples are for exim4 and postfix, two of the most common)
-
New Relic
-
Alaveteli can use New Relic's application monitoring tool to track the
performance of your production site. If enabled,
data from your application is gathered on the New Relic website, which you can inspect with
their visual tools. Basic use is free.
More information:
-
use the
agent_enabled: setting in the
the newrelic.yml config file to enable the New Relic analytics.
See the manual installation instructions.
-
see also the New Relic Ruby Agent github repo and
documentation
-
the New Relic website: if you've enabled the service,
you can log in to inspect the perfomance analytics
-
.po file (and .pot file)
-
These are the files needed by the gettext mechanism Alaveteli uses for
localisation. A
.pot file is effectively a list of all the
strings in the application that need translating. Each .po
file contains the mapping between those strings, used as keys, and their
translations for one particular language. The key is called the
msgid, and its corresponding translation is the msgstr.
-
production site (also: live, production server)
-
A production server is one that is running your Alaveteli site
for real users, with live data. This is different from a
development server, which you use make your
customisation and environment changes and try to get them to all work OK, or a
staging server, which is used for testing code
and configuration after it's been finished but before it goes live.
Your production site should be configured to run as efficiently as possible: for
example, caching is enabled, and debugging switched off.
Rails has a "production mode" which does
this for you: set
STAGING_SITE
to 0. Note that if you change this setting after you've
deployed, the rails_env.rb file that enables Rails's production
mode won't be created until you run rails-post-deploy.
If you have a staging server, the system environment of your staging and
production servers should be identical.
You should never need to edit code directly on your production server.
We strongly recommend you use Alaveteli's
deployment mechanism
(using Capistrano) to make changes to your production site.
-
publish
-
Alaveteli works by publishing the
responses it recieves to the
Freedom of Information
requests that its users send.
It does this by processing the emails it receives and presenting them
as pages — one per request — on the website. This makes it
easy for people to find, read, link to, and share the request and the
information provided in response.
-
recaptcha
-
Recaptcha is a mechanism that deters non-human users,
such as automated bots, from submitting requests automatically.
It requires the (human) user to identify a pattern of letters presented
in an image, which is difficult or impossible for a non-human to
do. Alaveteli uses this to prevent incoming spam.
-
redacting (also: redaction)
-
Redacting means removing or hiding part of a message so it
cannot be read: you are effectively removing part of a document from
your site.
This may be necessary for a variety of reasons. For example, a user may
accidentally put personal information into their request, or an
authority may include it in their response. You may also need to
redact parts of requests or responses that are libellous or legally
sensitive.
More information:
-
see the
admin manual
for more about how and when you may need to redact information
-
you can do text-only redaction with Alaveteli's
censor rules
-
some things are easier to redact than others — especially in PDFs,
things like signatures or images can be difficult to partially remove.
In such cases, you may need to remove the document entirely.
-
regular expression (also: regexp)
-
A regular expression is a concise way to describe a
pattern or sequence of characters, letters or words. As an administrator,
you may find regular expressions useful if you need to define censor rules. For example, instead
of redacting just one specific
phrase, you can describe a whole range of similar phrases with one
single regular expression.
Regular expressions can be complicated, but also powerful. If you're not
familiar with using them, it's easy to make mistakes. Be careful!
More information:
-
for example, the regular expression
Jo(e|ey|seph)\s+Blogg?s would match names
including
"Joe Bloggs", "Joey Bloggs" and
"Joseph Blogs", but not
"John Bloggs".
-
see Regular
Expressions on wikibooks for more information
-
release (also: release manager)
-
We issue new releases of the Alaveteli code whenever key
work (new features, improvements, bugfixes, and so on) have been added to
the core code. Releases are identified by their tag, which comprises two or
three numbers: major, minor, and — if necessary — a patch
number. We recommend you always use the latest version. The process is
handled by the Alaveteli release manager, who decides what
changes are to be included in the current release, and the cut-off date for
the work. Currently this is Alaveteli's lead developer at mySociety.
-
request
-
In Alaveteli, a request is the
Freedom of Information request
that a user enters, and which the site then emails to the relevant
authority.
Alaveteli automatically publishes
the responses
to all the requests it sends.
-
response
-
A response is the email sent by an
authority in reply to
a user's requests.
-
Ruby on Rails (also Rails)
-
Alaveteli is written in the Ruby programming language, using
the web application framework "Ruby on Rails".
-
Sass (for generating CSS)
-
Alaveteli's cascading stylesheets (CSS) control how the pages appear, and
are defined using Sass. It's technically a CSS extension
language, and we use it because it's easier to manage than writing CSS
directly (for example, Sass lets you easily make a single change that will
be applied to many elements across the whole site).
Rails notices if you change any of
the Sass files, and automatically re-generates the CSS files that the
website uses.
-
staging server (also: staging site)
-
A staging server is one that you use for testing code or configuration
before it goes live. This is different from a development server, on which you change the code and settings to
make everything work, or the
production server, which is the
site your users visit running with live data.
On your staging server, you should set
STAGING_SITE
to 1.
If you have a staging server, the system environment of your staging and
production servers should be identical.
You should never need to edit code directly on your production or staging servers.
We strongly recommend you use Alaveteli's
deployment mechanism
(using Capistrano) to make changes to these sites.
-
state
-
Each request passes through different
states as it progresses through the system.
States help Alaveteli administrators, as well as the public,
understand the current situation with any request and what
action, if any, is required.
The states available can be customised within
your site's theme.
-
theme
-
A theme is the collection of changes to the templates
and the code that causes the site to look or behave differently from the
default. Typically you'll need a theme to make Alaveteli show your own
brand.