This module supported our old public demo. It shouldn't be used as an example of how to configure the back end of the CWRC-Writer. A better starting point for understanding how to configure the CWRC-Writer for your own system is CWRC-GitWriter.
NPM module to which the CWRC-Writer delegates server side calls for file creation, retrieval, and update; entity lookups; schema retrieval; xml validation; template loading.
npm install cwrc-basic-delegator
To simultaneously register as a dependency in your package.json:
npm install cwrc-basic-delegator --save
or in shortcut form:
npm i -S cwrc-basic-delegator
let DelegatorConstructor = require('cwrc-basic-delegator');
let delegator = new DelegatorConstructor(cwrcWriter);
where cwrcWriter is an instance of the CWRC-Writer.
The spec directory contains specifications (tests) that can help better understand the API. Also see CWRC-Writer which fully uses the API of the delegator.
The API is for the moment defined on a class instantiated from the NPM module import (in other words, require(cwrc-basic-delegator) returns a constructor function with which to create the actual delegator.) The methods defined on the delegator are:
-
Fork or clone (depending on your role in the project) the repo to your local machine.
-
npm installto install the node.js dependenciesNOTE: we use
npm set save-exact trueto save dependencies as exact version numbers so NPM should install exact versions when you run install -
write a test (or two)for your new functionality (in 'spec' directory)
-
npm testto start mocha and automatically rerun the tests whenever you change a file -
change some stuff to satisfy new test
If you are working within a cloned copy, do the following to setup automatic semantic release through continuous integration using semantic-release (which in turn uses Travis) and commitizen. Otherwise, if you are working from a fork, then submit a pull-request.
Make sure you've got NPM configured to publish to the NPM registry:
npm set init.author.name "James Chartrand"
npm set init.author.email "[email protected]"
npm set init.author.url "http://openskysolutions.ca"
npm login (answer prompts approriately)
and install semantic-release-cli globally:
npm install -g semantic-release-cli
If necessary (it should already have been done, but maybe the NPM author information has changed for example) configure semantic release:
semantic-release-cli setup
which will ask you a series of questions, which at the time of writing this were:
semantic-release-cli setup
? What is your npm registry? https://registry.npmjs.org/
? What is your npm username? jchartrand
? What is your npm password? *******
? What is your GitHub username? jchartrand
? What is your GitHub password? ********
? What CI are you using? Travis CI
Semantic-release configures up a Travis build (on the Travis web site in the Travis account associated with the given Github username). The Travis build will deploy a new version to the NPM registry if the commited change is either a new feature or a breaking change.
To submit a commit, stage your changes (e.g., git add -A) then instead of using git's commit command, instead use npm run commit which uses commitizen to create commits that are structured to adhere to the semantic-release conventions (which are the same as those used by Google: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit )
The NPM ghooks package is used to add two pre-commit git hooks that will check that all mocha tests pass and that code coverage is 100% (as caluclated by istanbul) before allowing a commit to proceed. The hooks are set in package.json:
"config": {
"ghooks": {
"pre-commit": "npm run test:single && npm run check-coverage"
}
}
After the commit has succeeded then git push it all up to github, which will in turn trigger the Travis build. The Travis build is also set to confirm that all tests pass and that code coverage is 100%. This is set in the .travis.yml file:
script:
- npm run test:single
- npm run check-coverage
Of course, if the githooks that check tests and code coverage themselves passed, then the Travis check for tests and code coverage should also be fine.
Results of the travis build are here:
https://travis-ci.org/jchartrand/CWRC-BasicDelegator
The Travis build also publishes the code coverage statistics to codecov.io:
https://codecov.io/gh/jchartrand/CWRC-BasicDelegator/
codecov.io provides us with the code coverage badge at the top of this README.
Finally the Travis build publishes a new version (if the commit was designated as a new feature or breaking change) to NPM:
https://www.npmjs.com/package/cwrc-basic-delegator
Testing uses mocha and chai. Tests are in the spec directory.
This module makes http calls to CWRC. Rather than make those calls for every test, nock instead mocks the calls (intercepts the calls and instead returns pre-recorded data).
Please contact us if you'd like to contribute. Standard pull requests, including tests, are expected.
Who would use this?
The CWRC staff wanting to change how the CWRC-Writer saves to the CWRC server, and uses the CWRC server side services.