BEFORE STARTING ANY CONTRIBUTION TO THE PROJECT, PLEASE MAKE SURE YOU HAVE CAREFULLY READ THE README DOCUMENTATION AND THIS DOCUMENTATION AS WELL AND YOU ARE FAMILIAR ENOUGH WITH THE KOMFO UI PROJECT.

IF YOU HAVE QUESTIONS REGARDING THE FOLLOWING CONTRIBUTING GUIDELINES, OR NOT EXACTLY SURE HOW TO DEAL WITH SOME OF THEM, PLEASE CONTACT THE OWNER OF THE PROJECT FOR HELP.

Introduction

Technologies

Code

This projects is based on the following external projects:

• Bootstrap
• Normalize.css
• jQuery
• jQuery UI
• Select2

All UI developers must be familiar with those libraries in order to contribute to the project.

Styles

Stylesheets are product of Sass and Compass preprocessors tools.

Scripts

Scripts are written in pure JavaScript with the help of jQuery.

Documentation

All documentation pages are product of Hologram - a Ruby gem that parses comments (written in Markdown syntax) and helps you turn them into a beautiful style guide.

Task Runner

Komfo UI uses Grunt as a task runner and product builder.

Branches

There are two main branches with an infinite lifetime: master and production.

Note: Komfo UI is being developed under a git branching model similar to the one described in a popular article called A successful Git branching model. Check it out for more information.

Master branch

origin/master is the main branch where the source code of HEAD always reflects a state with the latest delivered development changes for the next release.

Production branch

origin/production is the main branch where the source code of HEAD always reflects a production-ready state. When the source code in origin/master branch reaches a stable point and it's ready to be released, all of the changes should be merged into origin/production, and then tagged with a release version. How this happens is described in a Releases section below.

Terms and conditions

Code conventions

Styles

Sass style sheets are being checked by scss-lint every time when there's a change during a development process.

Scripts

Scripts are being checked by JSHint every time when there's a change during a development process.

Commit messages

Komfo UI uses conventional-changelog to write all updates in a CHANGELOG.md file every time a new version is being released. That requires a strict form of commit messages. The preset that is used is angular.

Feature branch

Every new feature must be developed in a so called feature branch. It must be branched off from master at the beginning and when it's done - merged back into it. While branching off is a process that can be done with a single git command, merging back is required to be done with the predefined Grunt task called merge_feature. Once started it will expect to write a commit message that describes the feature. When written, it will do the rest.

Daily pushes

Every contributor must push its daily work to the central repo at the end of the day.

Merge requests

Every contributor must create a merge request when there are updates that needs to go into origin/master.

Installation

Requirements: Komfo UI project depends on Nodejs, npm, Grunt, Ruby and Bundler packages. Make sure you have all of them installed on your local machine before cloning the project.

To setup the development environment of Komfo UI and run the documentation locally, complete the next steps.

Clone the repo

At first make sure you have access to the insight GitLab environment.

If so, you may clone the project from one of the following Git URLs, depending on the secure connection you are going to use.

SSH

$ git clone git@gitlab.komfo.net:ui/komfo-ui.git
    

HTTPS

$ git clone https://gitlab.komfo.net/ui/komfo-ui.git
    

Fetch, Build & Serve

Now that you have the project locally, go to its root directory through the command line and trigger the next command:

$ npm start
    

This will:

• fetch all dependencies (npm install / bundle install)
• build the project (grunt build)
• serve the doc pages in the browser (grunt serve)

Note: If an error occurs for some reason, try to run every single command in the brackets above, one at a time, in the order they are written. If there's still an error, please contact the current DevOps goalkeeper.

Development

Dev (default)

Grunt task: dev

Build

Grunt task: build

Serve

Grunt task: serve

Assets

Fonts

Modify

Add

Icons

Glyphs

Social networks

Reactions

Miscellaneous

Images

Core

Elements

Components

Platform

Releases

Grunt task: prepare_release

Development release

Grunt task: release_snapshot

Production release

Grunt tasks: release_patch, release_minor, release_major