Skip to content
This repository has been archived by the owner on Jan 12, 2019. It is now read-only.

Latest commit

 

History

History
114 lines (79 loc) · 3.55 KB

CONTRIBUTING.md

File metadata and controls

114 lines (79 loc) · 3.55 KB
Raw

Setup

If you don't have Gulp and Bower installed, do it like so

npm install -g gulp bower

Fork this project into your own GitHub repo

git clone https://github.com/YOURNAME/firebase-util.git
cd firebase-util
npm install
bower install
gulp

Build, lint, minify, run all tests including end-to-end, and generally wreak havoc.

gulp

Scaffold a new class and create a unit test for it.

gulp scaffold -d DIRECTORY_UNDER_SRC -t class -n NameOfFile

Best Practices

Testing

Add test cases to cover any new code you create. Make sure all test cases pass before committing changes.

You can run all test units at any time using grunt test or automagically after changes by using grunt watch.

Read the README.md under test/ for details about test standards, structure, and helper methods.

Adding Libraries to Firebase.util

Structuring your data

Your package should be placed in src/mypackage/ and should contain the following structure:

src/package/libs/*.js  (the meat and classes of the new package)
src/package/exports.js (functions to be put into the Firebase.util public scope belong here)
src/package/README.md  (documentation and instructions for your package)

Write your code like any node module. You can use require() on other packages. Do not include external npm dependencies without Firebase team consent. You don't need to wrap all of your code in a function scope.

An example exports.js file:

// include global utils
var fbutil = require('../../common');

exports.tool1 = require('./libs/tool1');
exports.tool2 = require('./libs/tool2');

Debug Logging

The fbutil.log() function wraps console.log in a safe manner, allowing for filtering of log output.

Unlike console.log, if the first argument to any util.log function is a string, and it contains %s, %d, or %j, then it will be called with a printf-like logic and all other arguments are substituted into the string.

  • %s - String.
  • %d - Number (both integer and float).
  • %j - JSON.
  • % - single percent sign ('%'). This does not consume an argument.

Obey these conventions

  • begin each log with a Class name for easy filtering
  • choose the right severity
  • do not concatenate or parse json ahead of time, let the printf functions do that (for performance in production)

Choose the right severity

Use the escalation approach:

  • Don't enter a log message until you need it.
  • Start with debug()
  • The first time it helps you solve a problem, promote it to log()
  • If you use it frequently, promote it to info()
  • If it helps customers with the big picture, use info()
  • If it indicates config errors, common mistakes, or potential bugs use warn() or error()

All of the following are valid log function calls:

var log = util.pkg('log');
log('Class: hello %s', "world");
log('Class: json value: %j', {foo: bar}, 'more', 'args', 'not in sprintf');  // additional args are sent directly to console

log.debug('Class: hello %s', "world");
log.log('Class: hello %s', "world");
log.info('Class: hello %s', "world");
log.warn('Class: hello %s', "world");
log.error('Class: hello %s', "world");

Testing

Unit tests are written in Jasmine and run inside PhantomJS via Karma.

All packages must include a complete set of test units. They should be kept in test/ModuleName/**.spec.js. Check out test/lib/ for some common tools and existing tests for examples.

//todo End-to-end tests?