Development, in-depth documentation

The application

• MEAN stack, seeded originally with MEAN.js boilerplate: MongoDB, ExpressJS, AngularJS v1, NodeJS. Additionally stuff like Bootstrap, Leaflet etc.
• [[Database]] scheme (look for *.server.model.js project files to check most up to date info)
• We’re migrating the client to React. Read a migration guide.

The mobile app

We have a React Native app for Android written in ClojureScript: https://github.com/Trustroots/Trustroots-React-Native

Coding conventions

• Project has .editorconfig file, we recommend to download extension for your IDE.
• Build script checks all the files against our ESLint rules. Fix errors before submitting PR.

Most important

• Indentation with 2 spaces
• Beginning brace on the same line as the beginning statement
• File names use dash to separate words. For example: foo-bar.js
• Use camelCase for identifiers. Functions and variable names should be named like doAThing, not do_a_thing.

JS

• See Angular 1 Style Guide
• Somewhat along the lines of AirBnb JavaScript style guide (ESLint enforces these, too)
• We’re migrating to ES2018. Write your code in modern JavaScript. Read a migration manual.

CSS/LESS

• We use LESS CSS for CSS.
• Build as generic modules as possible. Rather .panel than .about-box.

CSS class names

• Name reusable bits of layouts by module names and keep them out of page styles, (eg. .group-badge can be used in multiple places around the site.)
• Related elements within a module use the base name as a prefix. For example module .panel has also .panel-header, .panel-body and .panel-footer.
• Prefix state rules with .is- (for example .is-collapsed).

Route conventions

TODO: Outdated

Convention is as follows:

• Url has the plural like /messages/, /users/, /users/:userId/photos, /users/:userId/references
• The id is the singular name followed by Id like userId, photoId, etc
• The route with the id is called nameSingle like usersSingle, offersSingle, etc
• Template name matches route name
• Nested routes are simply concatenated like usersSingleReferences or usersSinglePhotosSingle

Examples

• /users route name users
• /users/:username route name usersSingle
• /users/:username/edit route name usersSingleEdit
• /users/:username/photos route name usersSinglePhotos
• /users/:username/photos/edit route name usersSinglePhotosEdit
• /users/:username/photos/:photoId route name usersSinglePhotosSingle
• /users/:username/photos/:photoId/edit route name usersSinglePhotosSingleEdit
• /messages route name messages
• /messages/:userId route name messagesThread - deviates because it is userId not messageId

Testing

Strategy:

CI setup

Slowly getting there. Any help/experiences appreciated! #228

Unit tests

…mainly to test Mongo models (example).

…as well some critical bits of Angular frontend (example).

Integration tests

… mainly for the API routes (example).

End-to-end tests with Selenium

We have a free Automate account with Browserstack (#199, blog) — this is offered to us for free since we’re an open source project. This makes it very easy for us to test the project on tons of different browsers on various platforms, including MSIE.

Written in Python, using Selenium (#225).

(Selenium tests are currently out of date.)

Run tests

• npm test for everything,
• npm run test:server for Mocha tests,
• npm run test:server:watch same with watching,
• npm run test:client for testing Karma-unit tests and
• npm run test:selenium to run Selenium tests. Requires Python. Make sure Trustroots is running already as this task won’t spin it up first. This task isn’t included in the main test task. If you want to pass custom domain to test for Selenium you can do so by running: python ./scripts/selenium/test.py http://dev.trustroots.org/

Folder layout

You might want to read the folder structure to get a handle on how things are laid out. A quick summary:

• modules/ contains one folder for each “component” of the site, this is where most of the interesting stuff lives
• modules/**/server/ contains all the backend, server side stuff
  • /models defines the Mongoose models. There are only a few, so it might be worth scanning them to understand the data model. For in depth description, see [[database]].
  • /controllers as you’d expect, Express controllers live here.
  • /routes links url paths to controllers
  • /tests defines tests run server side
  • /jobs Agenda job scheduler (~cron) jobs (see config/lib/agenda.js for more)
  • modules/core/server/views contains email templates and initial rendered index.html
• modules/**/client/ contains all the client side stuff
  • modules/core/client/app
  • modules/core/client/app/less contains the site wide style variables and application.less file which includes rest of the modules.
  • /less is where you’ll find CSS styles in LESS format. Each module should have .less file with the module name, which then includes rest of the less files from the same folder. E.g.: modules/core/client/app/less/application.less includes modules/messages/client/app/less/messages.less which then includes inbox.less and thread.less from the same directory.
  • /views is where you’ll find templates
  • /services is where you’ll find Angular service, mostly for connecting to REST API points
  • /config contains the client side routes and other configs
  • /directives contains the Angular directives
  • /controllers contains the angular client side controllers
• config/ ta-da, configs! Server side.
  • /assets Defines paths for assets (serverside JS, frontend CSS/JS/LESS, lib files etc)
  • /lib/env primary config files. Don’t modify anything else here except local.js.
  • /lib/env/local.js file overriding other env/* files. Put here your adjustments you don’t want have publicly at the repo (it’s git-ignored).
  • /lib/agenda.js Agenda job scheduler (kinda like cron)
• bower.js frontend packages, managed with Bower
• package.js backend packages, managed with NPM
• fontello.conf.js config for icon font. Drag it to Fontello to edit.