Cloudify UI Common

This repository contains common static assets (images, fonts, styles, etc.) as well as JS library with functions reusable across Cloudify UI applications.

Table of Contents

• Installation
• Usage
  • ES module
  • CommonJS
  • Browser
• Documentation
  • External
  • Internal
• Development
  • Static files
  • JS API
• Debugging
  • Internal
  • External
• Deployment
  • When?
  • Who?
  • How?
    • Checklist
    • Steps

Table of contents generated with markdown-toc

Installation

npm install cloudify-ui-common

Usage

To load the package into your environment use one of the below presented option for getting icons module.

ES module

import { icons } from 'cloudify-ui-common';

CommonJS

const icons = require('cloudify-ui-common').icons;

Browser

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>

Check jsDelivr home page for details about the URL format. You can get specific version and/or specific file from the package.

Documentation

External

There is Cloudify Brandbook containing Cloudify Brand Guidelines we should follow creating new resources.

Internal

• API - exposed JavaScript API

• Configurations - shared development tools configuration files

• Fonts - shared common fonts

• Images - shared common images

• Styles - shared CSS, SCSS stylesheets

• Scripts - shared shell scripts

Development

Development environment is set up to enforce good practices in JS development (static code analysis, style formatting, code coverage check).

Some general guidelines for different type of assets are listed below.

Static files

• add new assets to dedicated folder for specific type
• when removing assets verify that it is not used anywhere
• if relevant and possible add documentation on asset usage (eg. in README.md file in the same folder as asset)

JS API

• add new code to src folder
• remember to export new files in src/index.js (otherwise the new code will not be available in the distribution package)
• build: npm run build (production build) or npm run dev (automatic rebuilding)
• test: npm test (static analysis, code style check, documentation check and unit testing with Jest testing framework)
• use prettier and eslint during development
• document your code (we are using JSdoc block tags as documentation is auto-generated using documentation.js)

Debugging

Internal

There is no standalone application for cloudify-ui-common, so the best way to debug some portion of it internally is using Jest unit tests (see: test folder).

External

If you want to develop/debug cloudify-ui-common from the package user side (eg. from cloudify-stage), then instead of using cloudify-ui-common package from NPM registry, you can:

1. Use npm link cloudify-ui-common <local-path-to-cloudify-ui-common> command in your package user project,
2. Build cloudify-ui-common project (see: Development section),
3. Run package user project and see changes applied locally in cloudify-ui-common.

Deployment

Cloudify UI Common library is published in NPM registry. See cloudify-ui-common@npm.

The way of work with publishing the package is described below. This section is divided into 3 parts:

1. When? - describes when we can publish the package,
2. Who? - describes who can publish the package and under which conditions,
3. How? - describes technical details to follow to publish the package.

When?

We can release when:

• code on master branch is necessary for one of the dependant projects (stage, composer, topology, ...),
• fix/feature on master branch is finished.

Who?

Developers from cloudify-rnd-ui e-mail group can publish new version after agreement with maintainer (see author or maintainers field in package.json file).

How?

This section is divided into two parts:

1. Checklist - describes prerquisities to be met before publishing the package,
2. Steps - describes technical steps to be executed to publish the package.

Checklist

• all your changes are merged to master branch, so that your local master branch is up-to-date,
• you know and follow Semantic Versioning rules when creating new version,
• you know and follow Keep a Changelog guiding principles when adding release notes,
• you have agreement with developers from cloudify-rnd-ui group on publishing new version.

Steps

If you met all points from the checklist above, follow these steps:

1. According to Semantic Versioning run one of the following scripts:

   • npm run publish:patch for new patch version,
   • npm run publish:minor for new minor version,
   • npm run publish:major for new major version,

   which will create special branch, add commit to it containing version bump in package*.json files according to your choice, tag the commit and push branch to remote. That should trigger Jenkins jobs finalizing publish.

2. Check if Jenkins jobs were successful.

3. Verify cloudify-ui-common @ NPM was updated properly.

4. Go to Create Release page @ GitHub to create release and add release notes according to Keep a Changelog guiding principles (in addition to the types of changes described there, you can use Internal type for all non-user-facing changes).