Merge pull request #47 from opentracing/bcronin/build_improvements

Build Node.js code with Babel, not as a webpack bundle

.eslintrc

@@ -6,7 +6,6 @@
     "node": true
   },
   "globals": {
-      "API_CONFORMANCE_CHECKS" : true,
   },
   "rules": {
       "consistent-return": [0],

CHANGELOG.rst

@@ -3,6 +3,11 @@
 History
 -------
 
+0.12.0 (2016-08-22)
+-------------------
+
+* Renamed the browser global symbol from `Tracer` to `opentracing`
+
 0.10.3 (2016-06-12)
 -------------------
 
@@ -19,3 +24,32 @@ History
 -------------------
 
 - Move to SpanContext, Reference, and `s/join/extract/g`
+
+
+0.10.0
+------
+
+This release makes the `opentracing-javascript` package conformant with the ideas proposed in https://github.com/opentracing/opentracing.github.io/issues/99. The API changes can be summarized as follows:
+
+- Every `Span` has a `SpanContext`, available via `Span.context()`. The `SpanContext` represents the subset of `Span` state that must propagate across process boundaries in-band along with the application data.
+- `Span.setBaggageItem()` and `Span.getBaggageItem()` have moved to `SpanContext`. Calls can be migrated trivially: `Span.context().{set,get}BaggageItem()`.
+- The first parameter to `Tracer.inject()` is now a `SpanContext`. As a convenience, a `Span` may be passed instead.
+- There is a new concept called a `Reference`; a reference describes a relationship between a newly started `Span` and some other `Span` (via a `SpanContext`). The common case is to describe a reference to a parent `Span` that depends on the child `Span` ('REFERENCE_CHILD_OF`).
+- `Tracer.startSpan(operation, fields)` no longer accepts `fields.parent`; it now accepts either `fields.childOf`, a `SpanContext` or `Span` instance, or `fields.references`, an array of one or more `Reference` objects. The former is just a shorthand for the latter.
+- `Tracer.join(operationName, format, carrier)` has been removed from the API. In its place, use `Tracer.extract(format, carrier)` which returns a `SpanContext`, and pass that `SpanContext` as a reference in `Tracer.startSpan()`.
+
+TL;DR, to start a child span, do this:
+
+::
+
+    let parentSpan = ...;
+    let childSpan = Tracer.startSpan('child op', { childOf : parentSpan });
+
+... and to continue a trace from the server side of an RPC, do this:
+
+::
+
+    let format = ...;  // same as for Tracer.join()
+    let carrier = ...;  // same as for Tracer.join()
+    let extractedCtx = Tracer.extract(format, carrier);
+    let serverSpan = Tracer.startSpan('...', { childOf : extractedCtx });

Makefile

@@ -1,40 +1,69 @@
-.PHONY: build clean publish test test_all
+# http://stackoverflow.com/questions/3774568/makefile-issue-smart-way-to-scan-directory-tree-for-c-files
+recursive_wildcard = $(wildcard $1$2) $(foreach d,$(wildcard $1*),$(call recursive_wildcard,$d/,$2))
 
-DST_FILES = \
-	dist/opentracing-node-debug.js \
-	dist/opentracing-node.js \
+CMD_BABEL = node node_modules/babel-cli/bin/babel.js
+SOURCES_JS = $(call recursive_wildcard,src/,*.js)
+COMPILED_PROD_JS = $(SOURCES_JS:src/%.js=lib/%.js)
+COMPILED_DEBUG_JS = $(SOURCES_JS:src/%.js=lib-debug/%.js)
+DST_BROWSER = \
 	dist/opentracing-browser.js \
 	dist/opentracing-browser.min.js
-SRC_FILES = $(shell find src/ -type f) \
-	webpack.config.js \
-	package.json
 
-build: $(DST_FILES)
-$(DST_FILES) : node_modules $(SRC_FILES)
-	npm run webpack
+.PHONY: build
+build: node_modules build-node build-browser
 
-clean:
-	rm dist/*.js
+# Compiles the ES6 source down to ES5 for greater compatibility across versions
+# of node.
+#
+# Also builds a 'lib-debug' version of the library that will do additional
+# runtime checks to help diagnose problems.
+.PHONY: build-node
+build-node: node_modules package.json $(COMPILED_PROD_JS) $(COMPILED_DEBUG_JS)
+lib/%.js: src/%.js
+	mkdir -p $(@D)
+	NODE_ENV=production $(CMD_BABEL) --presets es2015 --plugins transform-node-env-inline-and-fold $< -o $@ --source-maps
+lib-debug/%.js: src/%.js
+	mkdir -p $(@D)
+	$(CMD_BABEL) --presets es2015 $< -o $@ --source-maps
+
+# Use webpack to build a minified production bundle ande debug bundle for the
+# browser
+.PHONY: build-browser
+build-browser: $(DST_BROWSER) webpack.config.js package.json
+$(DST_BROWSER): $(SOURCES_JS)
+	npm run webpack
 
 node_modules:
 	npm install
 
+.PHONY: clean
+clean:
+	rm -rf node_modules/
+	rm -rf lib/ && mkdir lib
+	rm -rf lib-debug/ && mkdir lib-debug
+	rm -rf dist/apidoc
+	rm dist/*
+
+.PHONY: lint
 lint:
 	node node_modules/eslint/bin/eslint.js --fix --color src
 
 # NOTE: `npm version` automatically creates a git commit and git tag for the
 # incremented version
+.PHONY: publish
 publish: test
 	npm version patch
 	make build # need to rebuild with the new version number
 	git push
 	git push --tags
 	npm publish
 
+.PHONY: test
 test: build
 	node node_modules/eslint/bin/eslint.js --color src
 	npm test
 
+.PHONY: test_all
 test_all: build
 	scripts/docker_test.sh latest
 	scripts/docker_test.sh 5.8

README.md

@@ -1,17 +1,17 @@
-[![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]
-
 # OpenTracing API for JavaScript
 
 This library is a JavaScript implementation of Open Tracing API. It is intended for use both on the server and in the browser.
 
+[![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]
+
 ## Required Reading
 
 To fully understand this platform API, it's helpful to be familiar with the [OpenTracing project](http://opentracing.io) and
 [terminology](http://opentracing.io/spec/) more generally.
 
 ## Quick Start
 
-Install the package:
+Install the package using `npm`:
 
 ```bash
 npm install --save opentracing
@@ -59,38 +59,24 @@ Tracer.initGlobalTracer(TracingBackend.create());
 
 *Note: the underlying implementation object is shared between all inclusions of the `opentracing` package, so `initGlobalTracer` needs to only be called once during initialization.*
 
-## API Documentation
-
-There is a hosted copy of the current generated [ESDoc API Documentation here](https://doc.esdoc.org/github.com/opentracing/opentracing-javascript/).
-
-## Notes on backwards-incompatible changes
+### Usage in the browser
 
-### v0.9.x to v0.10.x
+The package contains two bundles built with webpack that can be included using a standard `<script>` tag. The library will be exposed under the global `opentracing` symbol:
 
-This release makes the `opentracing-javascript` package conformant with the ideas proposed in [opentracing/opentracing.github.io#99](https://github.com/opentracing/opentracing.github.io/issues/99). The API changes can be summarized as follows:
+* `dist/opentracing-browser.min.js` - minified, no runtime checks
+* `dist/opentracing-browser.js` - debug version with runtime checks
 
-* Every `Span` has a `SpanContext`, available via `Span.context()`. The `SpanContext` represents the subset of `Span` state that must propagate across process boundaries in-band along with the application data.
-* `Span.setBaggageItem()` and `Span.getBaggageItem()` have moved to `SpanContext`. Calls can be migrated trivially: `Span.context().{set,get}BaggageItem()`.
-* The first parameter to `Tracer.inject()` is now a `SpanContext`. As a convenience, a `Span` may be passed instead.
-* There is a new concept called a `Reference`; a reference describes a relationship between a newly started `Span` and some other `Span` (via a `SpanContext`). The common case is to describe a reference to a parent `Span` that depends on the child `Span` ('REFERENCE_CHILD_OF`).
-* `Tracer.startSpan(operation, fields)` no longer accepts `fields.parent`; it now accepts either `fields.childOf`, a `SpanContext` or `Span` instance, or `fields.references`, an array of one or more `Reference` objects. The former is just a shorthand for the latter.
-* `Tracer.join(operationName, format, carrier)` has been removed from the API. In its place, use `Tracer.extract(format, carrier)` which returns a `SpanContext`, and pass that `SpanContext` as a reference in `Tracer.startSpan()`.
-
-TL;DR, to start a child span, do this:
+### Node.js debug version
 
 ```javascript
-let parentSpan = ...;
-let childSpan = Tracer.startSpan('child op', { childOf : parentSpan });
+var opentracing = require('opentracing/debug');
 ```
 
-... and to continue a trace from the server side of an RPC, do this:
+Requiring `opentracing/debug` will include a version of the library with additional runtime checks that are useful for debugging but not desirable for production use.
 
-```javascript
-let format = ...;  // same as for Tracer.join()
-let carrier = ...;  // same as for Tracer.join()
-let extractedCtx = Tracer.extract(format, carrier);
-let serverSpan = Tracer.startSpan('...', { childOf : extractedCtx });
-```
+## API Documentation
+
+There is a hosted copy of the current generated [ESDoc API Documentation here](https://doc.esdoc.org/github.com/opentracing/opentracing-javascript/).
 
 ## Development Information
 
@@ -116,4 +102,3 @@ For truly implementation-dependent methods, the JavaScript API layer *does* expo
   [cov-img]: https://coveralls.io/repos/github/opentracing/opentracing-javascript/badge.svg?branch=master
   [ci]: https://travis-ci.org/opentracing/opentracing-javascript
   [cov]: https://coveralls.io/github/opentracing/opentracing-javascript?branch=master
-

debug.js

@@ -0,0 +1,5 @@
+// Entry-point for the debug library.  Allows for:
+//
+// var opentracing = require('opentracing/debug');
+//
+module.exports = require('./lib-debug');