Skip to content

Latest commit

 

History

History
97 lines (64 loc) · 6.01 KB

developer-guide.md

File metadata and controls

97 lines (64 loc) · 6.01 KB
Raw

Shunter Developer Guide

This guide is here to help new developers get started with developing Shunter itself. It will outline the structure of the application and some of the development practices we uphold.

If you're looking for information on how to use Shunter, please see the API Documentation.

Library Structure

The main files that comprise Shunter live in the lib folder. Shunter has been broken up into several smaller modules which serve different purposes. We'll outline the basics here:

  • benchmark.js exports a middleware which is used to benchmark request times.
  • config.js contains the default application configuration and code to merge defaults with the user config.
  • content-type.js is a small utility used to infer the content-type of a URL based on its file extension.
  • dispatch.js applies output filters to the content and returns the response to the client.
  • dust.js handles the application's Dust instance and registers some default helpers.
  • input-filter.js handles the loading and application of input filters.
  • output-filter.js handles the loading and application of output filters.
  • processor.js exports the middlewares Shunter uses for interacting with the request/response cycle.
  • query.js exports a middleware which attaches a parsed query string object to the request.
  • renderer.js handles compilation and rendering of Dust templates.
  • router.js parses the route configuration and routes requests to the correct back-end application.
  • server.js manages the lifecycle of the worker processes Shunter uses to serve requests.
  • shunter.js exports everything required for a Shunter application, and is the main entry-point.
  • statsd.js wraps a StatsD instance which is used to record application metrics.
  • watcher.js is a utility to watch a tree of files and reload them on change.
  • worker.js creates a Connect app to handle requests with the Shunter middlewares added to the stack. Instances of this app are run in each process managed by server.js.

Issue Tracking

We use GitHub issues to log bugs and feature requests. This is a great place to look if you're interested in working on Shunter.

If you're going to pick up a piece of work, check the comments to make sure nobody else has started on it. If you're going to do it, say so in the issue comments.

We use labels extensively to categorise issues, so you should be able to find something that suits your mood. We also label issues that might be a good starting-point for new developers to the project.

If you're logging a new bug or feature request, please be as descriptive as possible. Include steps to reproduce and a reduced test case if applicable.

Testing

We maintain a fairly complete set of test suites for Shunter, and these get run on every pull-request and commit to master. It's useful to also run these locally when you're working on Shunter.

To run all the tests, you can use:

make test

To run all the tests and linters together (exactly as we run on CI), you can use:

make ci

If you're developing new features or refactoring, make sure that your code is covered by unit tests. The tests directory mirrors the directory structure of the main application so that it's clear where each test belongs.

Static Analysis

As well as unit testing, we also lint our JavaScript code with JSHint and JSCS. This keeps everything consistent and readable.

To run the linters, you can use:

make lint

Versioning

Most of the time, one of the core developers will decide when a release is ready to go out. You shouldn't take this upon yourself without discussing with the team.

Shunter is versioned with semver. You should read through the semver documentation if you're versioning Shunter.

To publish a new version of Shunter:

  • Switch to the master branch, version commits are the only commits that shouldn't be in a pull-request
  • Increment either the major, minor, or patch version in package.json. If you're unsure which, have a chat about it or re-read the semver docs
  • Add an entry to HISTORY.md outlining the changes in the new version. Take your time, this log should be useful to developers building with Shunter
  • Commit your changes with a message like "Version 1.2.3" – this helps people find version commits in the log
  • Tag your newly created commit with the version number. E.g. git tag 1.2.3
  • Push both the commit and the new tags to origin: git push && git push --tags. It's really important to push tags as well!