Pattern Library

Copyright © 2017 - The University of Melbourne

The contents of this repository have been produced by The University of Melbourne for internal use and must not be distributed without the express permission of The University of Melbourne.

• Development Preview (Netlify deploy from dev branch)
• Production (Netlify deploy from master branch)

External usage

• How to use the library - how this library externally

Getting started

The design system requires:

• Node (v16)
• Yarn (latest version)

# 1. Clone the repository.
git clone https://github.com/unimelb/pattern-lib.git

# 2. Enter your newly-cloned folder.
cd pattern-lib

# 3. Copy the env file.
cp .env.example .env

# 4. Copy the git pre-push hook
cp pre-push.sh .git/hooks/pre-push

# 4. Install dependencies. Make sure yarn is installed: https://yarnpkg.com/lang/en/docs/install
yarn

# 5. Read the documentation linked below.

Development

• Contributing Guidelines

Storybook is the main development environment.

• yarn dev - http://localhost:7002/
• yarn build to build the documentation site to /.out/docs. Environment variable LOAD_EXTERNAL_ASSETS controls whether the documentation site is to load the library assets locally (false) or from the CDN (true).

Generator

This project includes generators to speed up common development tasks. Commands include:

# Generate a new component
yarn generate component

You will then be asked for the name of the component, this will be used to create a new folder with a minimal component layout and story

Note: Always remember to add the new component to the file index.js inside of the folders target/lib and target/vue, that way the component will be exportable to Matrix CMS via CDN and Vue via NPM.

# Generate a new view component
yarn generate story

You will need to select the component from the list of folders, then confirm the selection by selecting choose this directory. You will then be asked to give the story a name.

Note: This requires some special comments are added in the stories/index.js file. If it doesn't work make sure the comments are the same as in the template directory.

Using a component in CMS

In Storybook: When adding the "how to use a component" documentation, add a description that clearly shows that ( in the CMS environment) a component must be used in the way of closing the tag explicitly, as shown in the following example:

Do not:

(In the CMS, self closing tags won't load the component:)

# self close the components
<my-new-component/>

Do

(To be compatible with CMS, call the component this way:)

# explicitly closing
<my-new-component></my-new-component>

Note: Matrix CMS can only use the components in that way and must be in the target/lib folder as well. You can self-close a component when importing it in a parent component in the pattern-lib context. The rule described above applies just when the component is called in the CMS context. ie. footer component, which is used like this in CMS: <page-footer-alt></page-footer-alt> instead of <page-footer-alt />.

Targets

UI library - targets/lib

The main UI library for use in the CMS. The target provides a local development environment for testing purposes.

• yarn start:lib - http://localhost:7003/.
• yarn build:lib to compile the library to .out/lib/<version>, including ui.css, ui.js, sprite.svg, and SVG assets in components/shared. You can then use http-server or another static file server to serve the output directory.

The following environment variables are available to configure the behaviour of yarn build:lib:

• LOAD_EXTERNAL_ASSETS controls whether the library is to load its assets locally (false) or from the CDN (true).
• LIB_EMIT_HTML controls whether to emit the demo HTML file - set it to true to emit the file.
• LIB_LOAD_VERSION controls which version of the library to load in the demo:
  • leave it blank to load the local bundles (e.g. to test a new feature),
  • set it to auto to load the latest version from the CDN (i.e. the version specified in package.json),
  • set it to a specific version number to load that version from the CDN - e.g. 0.0.12 (no v prefix).

Vue library - targets/vue

The library with all the Vue components for use in single-page apps and other Vue-based projects.

• yarn build:vue to compile the library to .out/vue.js.

Linting

CSS files are linted on the fly with stylelint. The configuration file, .stylelintrc, extends two shared configuration: stylelint-config-standard and stylelint-config-property-sort-order-smacss.

JS files and single-file Vue components are linted on the fly with ESLint. The configuration file, .eslintrc, extends two shared configurations: eslint-config-airbnb and plugin:vue/recommended

For your own sanity, make sure to install your code editor's ESLint and stylelint extensions. The following commands are available for on-demand linting and fixing:

• yarn lint
• yarn lint:fix
• yarn lint:css
• yarn lint:css --fix
• yarn lint:js
• yarn lint:js --fix

Release process

At the start of a new release sprint:

• Create a milestone called next-release.

Throughout the release sprint:

• Assign the appropriate pr- label to every new PR: pr-major if it contains a breaking change, pr-minor if it adds a new feature, pr-patch in all other cases.
• Assign issues and PRs to next-release as they are resolved/merged.
• Assign additional labels to issues when relevant (e.g. deprecated, documentation, etc.)

At the end of the release sprint:

[!NOTE] > Note on versioning: the version number follows the semver convention MAJOR.MINOR.PATCH, where: MAJOR corresponds to a breaking change (e.g. a change in a component's markup), MINOR to a new feature (e.g. a new component, a new feature for an existing component, etc.), and PATCH to a bug fix or under-the-hood change (e.g. code clean-up, performance improvement, etc.)

1. Look at all the PRs that were assigned to next-release throughout the sprint and identify the highest-level of change (major, minor or patch). Deduce the next release's version number and rename the milestone accordingly.
2. Create a new release notes draft based on the following template: .github/RELEASE_NOTES_TEMPLATE.md.
3. Write the release notes by going through all the issues and PRs assigned to the milestone.
4. Deploy to production:
   1. Bump the version number in package.json (cf. note below).
   2. Commit the version change to the dev branch.
   3. Create a pull request to merge the dev branch into master - e.g. "Deploy v1.0.1".
   4. Wait for the mandatory checks to pass then select Create a merge commit
5. Once the library and documentation sites are deployed, publish the release notes and close the milestone.
6. Share the release on the design-systems slack channel using the following template:

@channel new `gen2` version `vx.x.x` is out: https://github.com/unimelb/pattern-lib/releases/tag/vx.x.x

[!TIP] Github Actions then automatically builds the library and syncs the output files to S3. If the version you're deploying had been previously deployed, you'll need to invalidate the files on the CDN (AWS Cloudfront) or wait a day or so for this to happen automatically. Once the library is deployed, follow the release process below.

Semi-automatic deployment to dev

Pre-release builds can be created like this (using the git pre-push hook behind the scenes):

[!NOTE] > Note on pre-release versions: These are legitimate semver versions. They have the format MAJOR.MINOR.PATCH-beta.NUMBER. Only these pre-release versions will be published on dev.

1. Check out a clean dev branch
2. in bash git push - this will increment the pre-release version number and make a commit to your local repository
3. in bash git push again
   • You will be prompted that this will trigger a build. Answer y
   • This will push (only) your version number change commit to the remote dev repo
4. After the normal checks a build with the new version will be triggered by Github Actions

Testing

Testing Pull-requests

You can test pull-requests on live sites by using ?preview=test-xxx where xxx is the pull-request number.

For example: https://study.unimelb.edu.au/?preview=test-2203 will load https://github.com/unimelb/pattern-lib/pull/2203

How could you test before going live?

Code changes to the remote dev branch triggers a Github Actions deploy into the AWS S3 Bucket in a folder called latest where the CMS team can appoint to latest and test it out before go to production.

Each pull request that is opened, also is automatically generated a comment with a preview link to test it.

Note: Always check Github Actions in your pull request checks to insure it is building properly, before merge into dev.

Supported browsers:

• last two versions of Chrome, Firefox and Edge
• IE 11
• Safari 8+
• iOS 8.4+
• Android 4.4+
• Firefox ESR (v52.x)

Recommended mobile devices for testing:

• iPhone 4S
• iPhone 6
• iPad 2
• Galaxy s5

Visual snapshot testing

You can run visual snapshot testing using yarn test:snapshots. This compares your changes against the latest visual snapshot. Failed snapshot tests will show a visual diff comparison in snapshots/__tests__/__image_snapshots__/__diff_output__.

If you wish to update the snapshots with your changes run yarn test:e2e:updatesnapshots.

Visual Regression Tests

[!IMPORTANT] These tests should be run exclusively on your local machine to detect visual regressions before merging your pull-request.

You can test your changes against live production sites to ensure nothing breaks.

• uses TEST_PREVIEW_ID located in .env - refer to env.example
• the list of production sites are located in /e2e/tests/regression/pages.json

Running regression tests

1. update your regression snapshots

[!TIP] Make sure to comment out TEST_PREVIEW_ID to use the dev branch as the base snapshots. Alternatively, you can use any pull-request id.

yarn test:update:regression

2. set the TEST_PREVIEW_ID to your desired pull-request id
3. run the regression tests to compare your pull-request againts the base snapshots

yarn test:regression

4. view the report

yarn test:report

Developer documentation

• Documenting stories - how to customise the content of the README panel for each story
• Icons - how to add new icons, and how to use icons in CSS and Vue components
• Contributing - how to get involved and contribute code

Example websites

• The following UoM websites are using these components on the new Squiz CMS (Gen 2). Documentation on how to use these components in Edit+ Gen 2 documentation

• University Home Page

• About Us

• Brand Hub

• MSpace