Skip to content

Latest commit

 

History

History
144 lines (89 loc) · 7.41 KB

README.contribute.md

File metadata and controls

144 lines (89 loc) · 7.41 KB

Contributing

To get back to the main README, click here.

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 (see demo) 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 unit tests with Enzyme for DOM testing without a browser. Jest & Enzyme, Pluralsight Course
ESLint Lint JavaScript as configured in the .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
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.

Continuous Integration

For Origami's SaaS-based continuous integration, UXF must enable a web hook.

GitHub

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

UXF will set your repo's Travis configuration for publishing to npm as described in the official Travis documentation:

A repository’s .travis.yml file can have “encrypted values”, such as environment variables, notification settings, and deploy api keys. These encrypted values can be added by anyone, but are only readable by Travis CI. The repository owner does not keep any secret key material. Please note that encrypted environment variables are not available for pull requests from forks.

BitBucket

BitBucket repositories can 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.js - 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. Rendering changes to the demo/index.html itself, however, does require a manual page refresh.

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

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

GitHub Pages

The component demo can be deployed to GitHub Pages by:

npm run gh-pages

The page can then be viewed at:

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

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.