Documentation for 2.0 version

README.md

@@ -1,29 +1,78 @@
 [![Build Status](https://travis-ci.org/dailymotion/vast-client-js.png)](https://travis-ci.org/dailymotion/vast-client-js)
-[![npm version](https://img.shields.io/npm/v/vast-client.svg)](https://www.npmjs.com/package/vast-client)
-[![Dependency Status](https://david-dm.org/dailymotion/vast-client-js.svg)](https://david-dm.org/dailymotion/vast-client-js)
-[![devDependency Status](https://david-dm.org/dailymotion/vast-client-js/dev-status.svg)](https://david-dm.org/dailymotion/vast-client-js#info=devDependencies)
+[![npm version](https://badge.fury.io/js/vast-client.svg)](https://badge.fury.io/js/vast-client)
 
-# VAST Javascript Client
-Vast Client JS is a Javascript library for parsing Digital Video Ad Serving Template (VAST) documents as close as possible to the Interactive Advertising Bureau (IAB) specification.
+# VAST Client JS
+Vast Client JS is a JavaScript library to fetch and parse Digital Video Ad Serving Template (VAST) documents.
 
-This library provides:
+This library provides three components:
 
- * A VAST parser, which validates the XML and translates it into a JS object.
- * A VAST tracker, which batches the tracking urls and provides methods for calling them.
+ * A **VAST Client** to fetch and parse VAST XML resources into JavaScript Objects.
+ * A **VAST Parser** to directly parse a VAST XML.
+ * A **VAST Tracker** to batch and call tracking URLs.
 
+For the full API documentation go [here](#api).
 
-Complies with [VAST 3.0 spec](http://www.iab.net/media/file/VASTv3.0.pdf).
+Complies with the [VAST 3.0 specification](http://www.iab.net/media/file/VASTv3.0.pdf) provided by the [Interactive Advertising Bureau (IAB)](https://www.iab.com/).
 
-## Documentation
-The [client](docs/client.md) documentation contains the basic information to parse a VAST URL/Document.
+## Get Started
+VAST Client JS is available as an NPM package and can be easily installed with:
+```Bash
+npm i vast-client
+```
+Then import the components you need.
 
-For more advanced use of the parser, see the [parser](docs/parser.md) documentation.
+### VASTClient
+If you need to fetch and parse VAST documents, you can use the **VASTClient**:
+```javascript
+import { VASTClient } from 'vast-client'
 
-All information about the tracking part can be found in the [tracker](docs/tracker.md) documentation.
+const vastClient = new VASTClient();
 
-## Support
-If you need to support legacy browsers (e.g. IE8+), don't forget to include [es5.js](/~https://github.com/inexorabletash/polyfill/blob/master/es5.js)
+vastClient.get('https://www.exampleVast.com/vast.xml', (err, res) => {
+  // Do something with the parsed VAST response
+});
+```
+In addition to fetching and parsing a VAST resource, **VASTClient** provides options to filter a sequence of calls based on count and time of execution, together with the possibility to track URLs using **VASTTracker**.
+
+### VASTParser
+To directly parse a VAST XML you can use the **VASTParser**:
+```Javascript
+import { VASTParser } from 'vast-client'
+
+const vastParser = new VASTParser();
+
+vastParser.parse(vastXml, (err, res) => {
+  // Do something with the parsed VAST XML
+});
+```
+
+### VASTTracker
+To track the execution of an ad use the **VASTTracker**:
+```Javascript
+import { VASTTracker } from 'vast-client'
+
+const vastTracker = new VASTTracker(vastClient, ad, creative);
+
+// Track an impression for the given ad
+vastTracker.trackImpression();
+```
+
+## API Documentation<a name="api"></a>
+The API documentation is organized by components:
+
+ * [VASTClient](docs/api/vast-client.md)
+ * [VASTParser](docs/api/vast-parser.md)
+ * [VASTTracker](docs/api/vast-tracker.md)
+
+**:warning: IMPORTANT :warning:** : the release of the `2.0` version of the library introduced many breaking changes in the API.
+
+Read the [**2.0 migration guide**](docs/api/2.0-migration.md) to update your project or follow the [**1.x API documentation**](docs/api/1.x) if you're still using the old version.
+
+## Support and compatibility
+The library is 100% written in JavaScript and the source code uses modern features like `es6 modules`. Make sure your environment supports these features, or transpile the library when bundling your project.
+
+A pre-bundled version of VAST Client JS is available: [`vast-client.js`](vast-client.js). You can add the script directly to your page and access the library's components through the `VAST` object.
 
 ## Build / Contribute
 
-See [CONTRIBUTING](CONTRIBUTING.md)
+See [CONTRIBUTING](docs/CONTRIBUTING.md)

docs/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+:tada: Thanks for being here :tada:
+
+We appreciate any kind of contribution: bug reports, feature requests and pull requests.
+
+Please read the following sections before making your contribution.
+
+## Report a bug / Request a feature
+To report a bug or request a feature, please [create an issue on GitHub](/~https://github.com/dailymotion/vast-client-js/issues/new) and follow the guidelines below.
+
+### Report a bug
+ * Explain the expected behaviour with a simple sentence
+ * Label the issue as a `bug`
+ * Provide the **steps** to reproduce your problem (if possible) or a simple **example** of code
+ * Report the **version** of the library you are using
+ * Is it a regression from a previous version?
+
+### Request a feature or suggest an enhancement
+If you see something that's missing or can be improved, please let us know!
+
+ * Explain which feature/improvement you would like to be added to the library.
+ * Label the issue as `feature`, `enhancement` or `discussion`
+ * If you can, suggest how you would do that :sunglasses:
+ * If you already coded it, feel free to open and link a pull request :man_technologist: :woman_technologist:
+
+## Pull requests
+Pull requests are welcome. Here is a quick guide on how to start.
+
+ * Develop in a dedicated branch, not directly on master
+ * If you add some logic, add some tests too
+ * Make sure test are passing (`npm test`)
+ * If you bundle the project, please don't commit the updated `vast-client.js` file in your PR. We'll take care of generating an updated build right before releasing a new tagged version.
+
+## Setup the project
+
+Clone the repository :
+```Bash
+git clone git@github.com:dailymotion/vast-client-js.git
+```
+
+Setup your environment :
+```Bash
+cd vast-client-js
+
+npm install
+```
+
+Run the tests :
+```Bash
+npm test
+```
+
+### Bundle
+
+The project uses webpack to bundle the assets (output will be `vast-client.js`):
+```Bash
+npm run build
+```

docs/RELEASE-TASKS.md

@@ -0,0 +1,17 @@
+# Release tasks
+
+This document describes release tasks used during the project life-cycle.
+We might want to automate some of them in a near future (e.g via Travis).
+For now, let's use this document to make sure everyone is on the same page.
+
+## Release a new version
+
+``` Bash
+git checkout master
+npm run test
+npm run Build
+git add . && git commit -m "Bundle release [release version number]"
+npm version <major|minor|patch> # depending on the changes
+npm publish
+git push --tags origin master
+```

docs/client.md → docs/api/1.x/client.md

@@ -1,10 +1,5 @@
 # VAST Client
-Get an instance of the `VASTClient` by importing and using the class constructor:
-``` javascript
-import { VASTClient } from 'vast-client'
-
-const client = new VASTClient();
-```
+The VAST Client is accessed through *DMVAST.client* object.
 
 ## Properties
 
@@ -13,37 +8,37 @@ Used for ignoring the first `n` calls. Automatically reset 1 hour after the 1st
 
 ``` javascript
 // Ignore the first 2 calls
-client.cappingFreeLunch = 2;
+DMVAST.client.cappingFreeLunch = 2;
 
-// Those following client.get calls won't be done
-client.get(VASTUrl, cb);
-client.get(VASTUrl, cb);
+// The following DMVAST.client.get calls won't be done
+DMVAST.client.get(VASTUrl, cb);
+DMVAST.client.get(VASTUrl, cb);
 
 // VASTUrl will be called
-client.get(VASTUrl, cb);
+DMVAST.client.get(VASTUrl, cb);
 ```
 
 ### `Number` cappingMinimumTimeInterval (default: `0`)
 Used for ignoring calls that happen `n` ms after the previous call. Minimum time interval is disabled if sets to `0`.
 
 ``` javascript
 // Ignore any call made 5 minutes or less after one.
-client.cappingMinimumTimeInterval = 5 * 60 * 1000;
+DMVAST.client.cappingMinimumTimeInterval = 5 * 60 * 1000;
 
 // Work
-client.get(VASTUrl, cb);
+DMVAST.client.get(VASTUrl, cb);
 
 // ...
 // 2 minutes later
 
 // Ignored
-client.get(VASTUrl, cb);
+DMVAST.client.get(VASTUrl, cb);
 
 // ...
 // 4 minutes later
 
 // Work
-client.get(VASTUrl, cb);
+DMVAST.client.get(VASTUrl, cb);
 ```
 
 ## Method
@@ -62,7 +57,7 @@ Fetch a URL and parse the response into a valid VAST object.
 * `Function` *done* – Method to be called once the VAST document is parsed. The VAST JS object is passed as the 1st parameter. If null, an error is provided as a 2nd parameter.
 
 ``` javascript
-client.get('http://example.dailymotion.com/vast.xml', function(response, error)
+DMVAST.client.get('http://example.dailymotion.com/vast.xml', function(response, error)
 {
   // process the VAST response
 });