Skip to content

Latest commit

 

History

History
178 lines (106 loc) · 8.86 KB

README.contribute.md

File metadata and controls

178 lines (106 loc) · 8.86 KB
Raw

Contributing

Overview

The use of Bower for dependencies is not sanctioned in Origami v2. Use npm with webpack or browserify instead.

Tech Description Learn More
React Fast-rendering, composable client-side components. Powering Up with React
React Intl API to handle translations, format dates, numbers, and strings.
Babel Compiles ES6 to ES5 to enjoy the new version of JavaScript today. Also transpiles JSX via babel-preset-react. ES6 REPL, ES6 vs ES5, ES6 Katas, Pluralsight course
Webpack Bundles npm packages and our JS into a single file. Includes source maps and hot reloading via webpack-dev-server. Quick Webpack How-to Pluralsight Course
Jest Automated tests with expect for assertions and React Test Utils and Enzyme for DOM testing without a browser. Pluralsight Course
ESLint Lint JavaScript as configured in .eslintrc. Reports syntax and style issues. Using eslint-plugin-react for additional React specific linting rules.
SCSS Compiled CSS styles with variables, mixins, and more. Pluralsight Course
Enzyme Enzyme is a JavaScript Testing utility for React that makes it easier to assert, manipulate, and traverse your React Components' output. Jest & Enzyme
Npm Scripts Glues all this together in a handy automated build. Pluralsight course, Why not Gulp?

This archetype includes a working example component that puts the above to use.

Cross-browser Compatibility

Inform the consumers of this component in README.usage.md of any necessary polyfills and how to use Polyfill.io to construct requests for specific features.

Continuous Integration

To hook up your project to Origami continuous integration, a one-time manual process is currently required.

Please send your request for one of the following GitHub or BitBucket options to: pearson-design-accelerator@pearson.com or HipChat

GitHub

GitHub repositories will integrate with Travis CI, which will publish to the public scope in Pearson's npm organization.

GitHub Pages

The component demo can be deployed to github pages by:

npm run build
npm run deploy

The page can then be viewed at:

http://pearson-higher-ed.github.io/component-archetype

BitBucket

BitBucket repositories will integrate with Solano CI, which will publish to the private scope in Pearson's npm organization.

Initial Machine Setup

  1. Install Git.
  2. Install Node 6.0.0 or greater - Need to run multiple versions of Node? Use nvm.
  3. On a Mac? You're all set. If you're on Windows, complete the steps for your OS below.

On Windows:

  1. Install Ruby as the runtime engine for SCSS.
  2. Install Python 2.7. Some node modules may rely on node-gyp, which requires Python on Windows.

Quick Start

See the project working before changing anything!

In your local repo:

npm install
npm start

Navigate to: localhost:8081/component-archetype/

Where are the files being served from?

Webpack serves your component in memory when you npm start. No physical files are written. When the component is built using npm run build, physical files are written to /build.

Additionally, Hot Module Replacement is activated in the webpack dev server; saved changes to /src are automatically reloaded in the browser. Changes to the demo/index.html itself, however, do require a manual page refresh.

Using ElementsSDK

Pearson has created a base styling library to assist developers in creating a user interface with styles that are pre-approved by the design team. For the purposes of this component archetype the incorporation of ElementsSDK is for the purposes of the demo only, but it is possible that the component archetype demo does not pull in the latest version of ElementsSDK. Should the demo need to be on the latest ElementsSDK version, please update the package.json file to reflect the current version of ElementsSDK

Additionally, given the scope of ElementsSDK, developers will need to consider if incorporating ElementsSDK into their component as a direct dependency is warranted.

Build

Build the bundle(s) manually at any time, and minify all JavaScript for production:

npm run build

Unit Test

The project is wired to unit test with the popular Jest framework and the expect assertion library.

It is also enabled for the following options:

  • shallow rendering with React's test utilities

  • Rendering a component into a detached DOM node in the document, using jsdom

  • Airbnb's Enzyme for DOM manipulation and traversal. Enzyme

Code coverage report generated by Jest when the tests are run. The report can be viewed when you run:

npm test

npm start

go to ---> http://localhost:8081/coverage/lcov-report/

if you've deployed your project to github pages as detailed above:

go to ---> http://pearson-higher-ed.github.io/component-archetype/coverage/lcov-report/

Linting will run automatically prior to executing the test suite.

npm test

Functional Test

When ready, turn on Selenium-based automated testing for QA, by un-commenting ./test/shell_scripts/run_tests.sh in the CI configuration (.travis.yml or solano.yml).

Spec Compliance

Determine if your component passes a series of checks for Origami v2 compliance.

npm run verify

Translations for Internationalization

It is expected that applications will pass in translated text for dynamic content, and your component simply needs to render whatever is passed in.

For text inherent to the component (e.g. button text or input placeholder), add JSON translations for each supported locale to the translations folder, and use the locale configuration parameter.

Publish to Pearson npm Registry

FOR PUBLIC PACKAGES ONLY, add the following npm script to the package.json:

"postpublish": "npm access public && echo 'Package scope set to public!'"

Do not manually version or tag your project. Instead, when you are ready to publish an update to npm, manually run the release script in the master branch. It handles all of that and publishes to npm on your behalf using the pearson-ux account.

Additionally, there is no need to manually maintain a change log - if you follow the commitizen conventions for commit messages, a change log will automatically be generated during the release process.

Before you run the release script, ensure that you don't have to manually authenticate every time you perform a network operation with Git.

npm run release

How do I debug?

Source maps are enabled for the webpack dev server. Using Chrome's dev tools - open the "Sources" tab, navigate to top/webpack://./, and you will find the original source files for which you can set breakpoints in Chrome's debugger.

To take advantage of source maps, you must enable JavaScript source maps in your browser.

Optionally, install React developer tools for additional React debugging support in Chrome dev tools under the "React" tab.