Decko application code used at Wikirate.org

Code Organization

WikiRate is a website built with Decko, or a "deck."

Decko code is primarily written in Ruby, and ruby code is typically distributed in libraries called "gems." Decko code has a few main core gems (decko, card, and cardname), and then everything else is organized into mods, which you can think of as short for "modules" or "modifications".

Repositories

WikiRate developers work with mods in three different main GitHub repositories:

1. wikirate/wikirate – this repo.
2. decko-commons/decko, which contains code for core gems and the mods that are included by default in new decks. It is included as a submodule of this repo at vendor/decko.
3. decko-commons/card-mods, which contains other mod gems developed by Decko Commons. It's included here at vendor/card-mods

Directories

A quick overview of the purpose of each directory in this repo:

• .semaphore configures our continuous integration testing with Semaphore.
• config is for configuration settings, many of which will vary between installations.
• cypress is one of our integration testing tools.
• db is for database seed data and migrations (may soon be moved into mods).
• files is where uploaded images and other files are stored.
• lib contains a few rake tasks and deployment scripts (will soon be moved into mods).
• log stores logs from web requests, tests, etc.
• mod is where we keep mods, the main WikiRate code. More details below.
• public files are exposed to the web. (It's mostly symbolic links to the public directories in mods.)
• script contains lots of one-off scripts, eg for data transformations.
• spec contains configuration for rspec tests. (The tests themselves are in mods.)
• tmp holds caches and other temporary data.
• vendor contains git submodules, including decko and card-mods.

Mods

Inside the mod directory there are many mod directories and a file named Modfile. When a deck has a Modfile, it means we've specified a load order for the mods.

WikiRate's Modfile is more involved than most, but it's reasonably well commented. The mods can be grouped into four main groups:

1. mods prefixed with deckorate_. DeckoRate is an abstraction of WikiRate; it has metrics, records, sources, datasets, etc, but the subject might be something other than companies – could be governments, geographical areas, or whatever else. It's more of an idea than a reality thus far, but we're trying to organizing code to help us approach that reality, and these mods are moving us in that direction. The idea is that some day these would all be made into gems and shared.
2. mods prefixed with wikirate_. This code is very narrowly WikiRate-specific and is unlikely to be very useful to others, so we're not likely to share it.
3. more broadly useful mods. Mods like guides and posts are likely to be useful to other decko users, and not just those creatings sites that follow the DeckoRate pattern. We will soon move them to card-mods.
4. todos. other mods don't really fit neatly into any of these categories and need to refactored until they do.

The mod page on docs.decko.org has details about mods' subdirectory structure and is a good place to start if you're learning to be a Decko monkey.

Setting up a Development Environment

The following will help set up a functioning wikirate site with a small subset of (mostly fake, largely silly) WikiRate data.

1. Install basic dependencies

First, you will need to install Decko dependencies, including ruby, bundler, ImageMagick, MySQL, and a JavaScript runtime.

2. Get code from GitHub

Then you will need to make your own fork of the WikiRate GitHub repository. Each WikiRate developer maintains their own fork so they can make pull requests from that fork. For example, Ethan's fork is at https://github.com/ethn/wikirate.

If you don't already have a GitHub account, start by signing up. If you're logged in, you can fork by clicking the "Fork" button in the upper right hand corner of the repo page.

Now we pull that code down to our computers.

git clone git@github.com:YOURNAME/wikirate.git

At this point we have the main wikirate repo, but there's a lot more code we need in nested repositories, which git calls submodules. The following command will pull down the latest submodules, including the decko, card-mods, and others that we don't maintain.

cd wikirate
git submodule update -f --init --recursive

3. Install ruby gems

Nearly all ruby developers these days use a beloved gem management tool called bundler. Bundler defines the "bundle" of gems you need for your application. "bundle install" will install all those gems.

bundle install

Pay close attention to any error messages. Some gems may have additional dependencies that need to be installed or identified for the bundle installation to complete successfully.

4. Add configurations

Each copy of the Wikirate site can have different configuration options for its own purposes. The production site, for example, is configured to store files and images on the cloud, but by default your local test site will just store files locally. Since the main config files are not shared (and often contain private credentials), they are not tracked in git. However, you must have these files in place for your site to function, so you can start by copying over a sample set:

cp -R config/sample/* config

These configurations should typically work out of the box, but at some point you may wish to change:

• config/database.yml for unusual database configs
• config/application.rb to change most other configurations
• config/environment/[environment].rb for configurations that only apply to certain environments (test, development, production, etc.).

5. Seed and serve

Now we seed the database with our silly data and start the server:

env RAILS_ENV=test bundle exec decko setup
bundle exec decko server

You should now be able to access a copy of your site at http://localhost:3000. You can log into the test data with:

• joe@user.com / joe_pass, or
• joe@admin.com / joe_pass

Updating your code

To get the latest code you will need to do the following:

git pull                             # pull the latest wikirate/wikirate code
git submodule update -f --recursive  # update the nested git repositories
bundle update                        # get the latest gems 
bundle exec decko update             # run migrations and install mods

Testing

Running Tests

All tests required a populated test database

bundle exec rake decko:seed:replant

RSpec

We use RSpec for unit and functional ruby tests.

bundle exec decko rspec                          # full syntax
bundle exec decko rs                             # shortcut
bundle exec decko rs -- /my/file/is/here_spec.rb # runs a specific test

Tests are found in the spec dir of most mods.

Cypress

Cypress is our preferred tool for integration tests. To get it running, you will need to install node

Typically you will want two different shells active for cypress testing: one for a server

RAILS_ENV=cypress bundle exec decko server -p 5002

...and another for running the tests

yarn install
yarn run cypress run

Tests are found in the spec/cypress dir within mods.

Cucumber

We've been slowly moving away from cucumber in favor of cypress, but we still have some cucumber tests.

bundle exec decko cucumber
bundle exec decko cc          # shortcut

Tests are found in the features dir within mods.

Deploying Changes

Requires server permissions.

TODO!

Maintenance messages

See documentation here: https://github.com/capistrano/maintenance

quick examples:

  # turn on maintenance message with defaults
  cap production maintenance:enable

  # turn on maintenance message with more info
  cap production maintenance:enable REASON="database update" UNTIL="in a minute or two"

  # turn maintenance message off
  cap production maintenance:disable