README.md

We Vote Base

Need to work with US ballot or election related data? In this Python-Django project, we import election related data from a variety of sources, merge it, and provide models to work with this data. We Vote Education (the sponsor of this project) is a nonprofit applying for 501(c)(3) status. We would like to empower more civic hackers by providing a living guide to working with election related data.

Our approach is to write importers that take data from these sources into a local database, and then merge that data into a We Vote database structure so we can deliver a complete ballot to any American voter.

WeVoteBase is currently configured (in manage.py) to look for a "wevotebase/local.py" file (configured in the
"wevotebase/settings.py" file). When we run this on a production server, we will startup with a production settings
file like "production_heroku.py".

Copy "environment_variables-template.json" to "environment_variables.json". You will configure many variables for your
local environment in this file. New variables needed by WeVoteBase will be added to
"environment_variables-template.json" from time to time, so please check for updates by comparing your local version
with the template file.

LOG_FILE

Create a file on your computer to match the one expected in the environment_variables.json file:

As configured in github, only errors get written to the log.
Logging has five levels: CRITICAL, ERROR, INFO, WARN, DEBUG.
It works as a hierarchy (i.e. INFO picks up all messages logged as INFO, ERROR and CRITICAL), and when logging we
specify the level assigned to each message. You can change this to info items by changing this:

LOG_FILE_LEVEL = logging.INFO

GOOGLE_CIVIC_API_KEY

If you are going to connect to Google Civic API, add your key to this variable.
TODO: Describe the process of getting a Google Civic API Key

Setup - Database Creation

If you would like to match the local database settings from the "wevotebase/environment_variables.json" file,
(Search for "DATABASES"):

createdb WeVoteDB

Populate your database with the latest database tables:

python manage.py makemigrations
python manage.py migrate

Create the initial database:

$ python manage.py syncdb

When prompted for a super user, enter your email address and a simple password. This admin account is only used in development.

If you are not prompted to create a superuser, run the following command:

In the wevotebase/setting.py file, search for "Heroku". There are comments that tell you which parts of the settings file to comment or uncomment to get a version running on Heroku.

Import Test Data

Start up the webserver:

python manage.py runserver

Open your browser to login to the admin account so you can have access to the import_export tools:

http://localhost:8000/admin/login/?next=/admin/

Visit the site here:

http://localhost:8000/import_export/

Click all the import links, going from top to bottom.

Now go back to the root and you should be taken to a San Francisco ballot.

http://localhost:8000/

Coding Standards

Please use descriptive full word variable names.

In the lifecycle of most projects, fixing bugs and maintaining current features end up taking 50%+ of total engineering time.

Our goal is to create a code base that is easy to understand, making fixing bugs and maintaining current features as painless as possible. We will have many engineers working with this code, and we want to be welcoming to engineers who are new to the project.

Short variable names can often create confusion, where a new engineer needs to spend time figuring out what a short variable name actually means. (Ex/ “per” or “p” instead of “person”.) For this project please use descriptive full word variable names.

Fellow engineers should be able to zoom around the code and not get stopped with riddles created by short names.