youyesyet

A web-app intended to be used by canvassers campaigning for a 'Yes' vote in the second independence referendum.

The web-app will be delivered to canvassers out knocking doors primarily through an HTML5/React single-page app designed to work on a mobile phone; it's possible that someone else may do an Android of iPhone native app to address the same back end but at present I have no plans for this.

There must also be an administrative interface through which privileged users can set the system up and authorise canvassers, and a 'followup' interface through which issue-expert specialist canvassers can address particular electors' queries.

generated using Luminus version "2.9.11.05"

Status

Very early pre-alpha; user interface mostly works (enough to demonstrate), back end is hardly started.

What is it supposed to do?

To understand what I'm aiming for, read this essay. Design documentation, such as there is of it yet, is in the dummy sub-directory. Also look at src/clj/youyesyet/db/schema.clj.

Prerequisites

You will need Leiningen 2.0 or above installed. The database required must be Postgres 9.3 or above.

You'll also need to create your own local copy of profiles.clj, which should contain something like:

;; WARNING
;; The profiles.clj file is used for local environment variables, such as database credentials.
;; This file is listed in .gitignore and will be excluded from version control by Git.

{:profiles/dev  {:env {:database-url "jdbc:postgresql://127.0.0.1/youyesyet_dev?user=username&password=thisisnotsecure"}}
 :profiles/test {:env {:database-url "jdbc:postgresql://127.0.0.1/youyesyet_test?user=username&password=thisisnotsecure"}}}

Where username is the username required to access the database, and thisisnotsecure is the password which authenticates that username.

It will be helpful for you to have the Zenhub plugin in your browser, either Firefox or Chrome, as I'm using it for project planning.

Building this

This application is built using Application Description Language. The adl pre-processor is run as a prep task to building the uberjar, which in turn is preparatory to building the uberwar.

This will generate a large number of the source files required by YouYesYet, including the database initialisation scripts. These generated source files are not, as a matter of policy, held in the repository.

What is auto-generated, and how to override it

The following files are generated from the master file youyesyet.adl.xml:

resources/sql/queries.auto.sql - HugSQL queries for selection, insertion, modification and deletion of records of all entities described in the ADL file.
resources/sql/[application-name].postgres.sql - Postgres database initialisation script including tables for all entities, convenience views for all entities, all necessary link tables and referential integrity constraints.
resources/templates/auto/*.html - Selmer templates for each form or list list specified in the ADL file (pages are not yet handled).
src/clj/[application-name]/routes/auto.clj - [Compojure]() routes for each form or list list specified in the ADL file (pages are not yet handled).
src/clj/[application-name]/routes/auto-json.clj - [Compojure]() routes returning JSON responses for each query generated in resources/sql/queries.auto.sql.

You are strongly advised never to edit any of these files.

To override any query, add that query to a file resources/sql/queries.sql
To add additional material (for example reference data) to the database initialisation, add it to a separate file or a family of separate files.
To override any template, copy the template file from resources/templates/auto/ to resources/templates/ and edit it there.
To override any route, write a function of the same name in the namespace [application-name].routes.manual.

Getting the database up

You'll need a file profiles.clj, with content similar to the following; it's not in the repository because it contains passwords.

;; WARNING
;; The profiles.clj file is used for local environment variables, such as database credentials.
;; This file is listed in .gitignore and will be excluded from version control by Git.

{:profiles/dev  {:env {:database-url "jdbc:postgresql://127.0.0.1/youyesyet_dev?user=youyesyet&password=yourverysecurepassword"}}
 :profiles/test {:env {:database-url "jdbc:postgresql://127.0.0.1/youyesyet_test?user=youyesyet&password=yourverysecurepassword"}}}

Do get the database initialised, run

createdb youyesyet_dev

I'm no longer using Migratus as I'm using Application Description Language to generate the majority of the application, and, as changes are made to the application description, new database schemas are generated. The database initialisation script will be found at resources/sql/youyesyet.postgres.sql. Manually maintained overrides are found in resources/sql/youyesyet.postgres.overrides.sql. So to initialise the database, invoke

psql youyesyet_dev < resources/sql/youyesyet.postgres.sql

followed by

psql youyesyet_dev < resources/sql/youyesyet.postgres.overrides.sql

Reference data initialisation scripts will in due course be stored in the same directory.

Once we have a more or less finished application it may be worth going back to Migratus; I might have a go at generating migrations from diffs between successive versions of the application description.

Running in a dev environment

To run in a dev environment, checkout the develop branch

To download and install Javascript delendencies, run

cd youyesyet
lein npm install

To start a development web server for the application, run:

Then

lein repl

Wait for the clojure user=> prompt to appear, and enter

(mount/start)

This will get the application running for development; ideally, open a new terminal and invoke

lein figwheel

which will aid in work on the ClojureScript components.

Running in a production environment

Either

run lein uberjar and execute the resulting jar file directly; or
run lein uberwar and serve the resulting war file from a servlet container.

The beta production server currently runs an uberwar build in Tomcat behind Nginx.

Working on this project

You should get the ZenHub plug-in for your favourite browser; I use ZenHub for project management, and you (and I) will find collaborating much easier if you do. To join in

Clone the project from my repository;
Visit the kanban board and choose an issue you'd like to work on;
Assign that issue to yourself and move it into the 'in progress' column;
Use gitflow: start a new feature;
Work on the issue;
When you are satisfied with your work, commit it to your repository in your feature branch;
Submit a pull request and move the issue to the 'QA/Review' column on the kanban board;
If your work works, I'll integrate it into the develop branch, which you can then pull;
Rinse and repeat!

Obviously I'd appreciate it if you'd mail me to introduce yourself, but there's no need to do so.

Finally, if you take a ticket and are not able to finish it, please

mail me to say so;
move the issue back to the 'backlog' column on the kanban board.

And many thanks!

More about tooling

Note that all tools recommended in this document are free for non-commercial use; not all are open source.

Editors/IDEs

I (Simon) use, like and recommend LightTable as my editor; I used to use Emacs, and there is excellent Clojure tooling for Emacs, but these days Emacs ways of working seem just too far from everything else to be comfortable to me. NightCode is a lighter-weight Clojure IDE which you may like. There's also Cursive but it isn't free and I have so far found it more annoying than helpful; or Counterclockwise which I don't have recent experience of.

Git

I'm currently using GitKraken, on Linux, Windows, and Mac. Like so many things it works best on Linux, but it's good on both other platforms. However, I confess that although I like the ability to easily view the whole structure of the git repository, I tend to drop back to the command line if I'm doing anything tricky with Git.

Database

The database is Postgres. I have no plans even to support anything else; I don't feel we have time to mess about. However, if someone wants to fork the code and implement a different database, that's up to them. I'm afraid I do all database stuff from the command line; there are graphical tools for Postgres but personally I've never found graphical tools for databases much use.

License

Licensed under the GNU General Public License, version 2.0 or (at your option) any later version.

NOTE THAT files which are directly created by the Luminus template do not currently have a GPL header at the top; files which are new in this project or which have been substantially modified for this project do have a GPL header at the top.

simon-brooke / youyesyet

readme