Contributing

The good news:

• Most everything is automated through npm scripts and package.json.

The bad news:

• It’s a little … byzantine.

Required Tooling

• node & npm
• jekyll to work on the content locally — yes, this will require getting a working Ruby installation
• plantuml to generate lovely diagrams, such as the one later in this doc
• dart-sass to compile CSS — technically, any sass will do, but you’ll have performance problems with the others

Build Pipeline

For performance and consistency, most of the content for Skyline is actually data driven. That is, if you’re writing HTML by hand you’re probably doing it wrong. Visually, the system looks like this:

Development Process

Easy mode:

npm start

This starts up the next five items. Alternatively, you can do them one at a time.

Start up the CSS pipeline:

npm run sass

Start up the JSONSchema-to-Typescript pipeline:

npm run schema:watch

Start up the Typescript-to-Javascript pipeline:

npm run assets:skyline

Start up the template pipeline:

npm run template:watch

Start up the Jekyll pipeline:

npm run jekyll:serve

Once those are up and running, changes to most things will yield changes in the browser. Most of those watchers, including Jekyll, will also occasionally get confused when you add new files, and will need to be restarted.

Some changes won’t get caught by the watchers. In those cases, you can force a full sync, which isn’t as expensive as it sounds:

npm run template

To make sure you haven’t completely trashed anything:

npm test

Those tests won’t catch every problem, but they’ll catch the big ones.