# Developers guide. 

## **NEW:** Updated version of node.js
This project requires 14 version of node.js. From now on we are using yarn as package manager. To install dependencies use command *yarn install --frozen-lockfile*

## Commit Guidelines
This project is now using the semantic-release npm plug-in to control versioning.  This means that it will automatically bump the version numbers when the CI build occurs.
The decision on whether this is a patch, feature or breaking (b.f.p) release is based upon the GIT commit messages. We are using the [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)

| Commit message                                                                                                                                                                                   | Release type               |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
| `fix(pencil): stop graphite breaking when too much pressure applied`                                                                                                                             | Patch Release              |
| `feat(pencil): add 'graphiteWidth' option`                                                                                                                                                       | Feature Release  |
| `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | Breaking Release |

## Table of Contents

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Starting application](#starting-application)
- [Available Tasks](#available-tasks)
- [Template system](#template-system)
- [Project structure](#project-structure)
    - [Markup](#markup)
    - [Css](#css)
        - [Responsive design](#responsive)
    - [Js](#js)
    - [Fonts](#fonts)
    - [Data](#data)
- [Gitflow](#gitflow)
- [Linting](#linting)
- [Design](#design)

Follow these rules to start application

# Prerequisites

You should have installed:

### `Node.js`
Node.js is a cross-platform JavaScript run-time environment for executing JavaScript code server-side.
You can download it here https://nodejs.org/en/download/

### `Gulp`
Gulp is a streaming build system.
Installation guide can be found here https://gulpjs.com/

# Installation

Go to https://gitlab.com/wickesit/cloudshop/cloudshop/html-prototype and clone repository to your local machine.
Then install all dependencies via:

```
$ yarn install --frozen-lockfile
```

# Starting application

### ```$ gulp```

This command runs the application.
Automatically opens browser on application main page.

# Available tasks

>Note: These commands are included in the default gulp task so there is no need to run it manually.

### `$ gulp build`

Builds entire application in `src/` folder and put it into `build/` folder.

### `$ gulp webserver` 

Runs webserver on the localhost

### `$ gulp watch`

Starts watching for changes in `src/` folder and reload the page after any occurs.

# Template system

We use **Handlebars** web template system.

Checkout the official Handlebars docs site at http://www.handlebarsjs.com and the live demo at http://tryhandlebarsjs.com/.

# Project structure

## Markup

All markup pages are placed at `src/` folder.
Concrete page extends some layout located in the `src/layouts/` folder
and define content of layout slots, such as `head`, `header`, `body`, `footer` and `foot`.
More information about handlebars layouts can be found here: https://www.npmjs.com/package/handlebars-layouts.
Layouts uses common partials placed at `src/partials/` folder.
Common components placed at `src/components/` folder.

```
html-prototype/
  src/
    layouts/
      base.html
    partials/
      header.hbs
      footer.hbs
    components/
      range-card.hbs
    index.html
    some-page.html
```

## Css

We use [Sass (an extension of CSS)](https://sass-lang.com/) to develop css.
Below you can find our sass files structure:

```
html-prototype/
  src/
    scss/
      common/
        _common.scss
      components/
        _card-slider.scss
        ...
      helpers/
        _mixins.scss
        _variables.scss
        ...
      libs/
        bootstrap4-scss/
        swiper.css
      pages/
        home.scss
        page_range-list.css
      partials/
        _breadcrumbs.scss
        _footer.scss
      main.scss
```

The idea of this structure is next:
- `main.scss` contains imports of all the scss except files, that are located in `pages/` folder;
- `common/` folder contains general site styles;
- `components/` folder contains styles for every concrete component;
- `helpers/` folder contains different utilities such as variables and mixins that wouldn't be compiled into css directly;
- `libs/` folder contains vendors styles;
- `pages/` folder contains page spesific styles;
- `partials/` folder contains partial spesific styles.

**Note:**
- all components should be imported in the main.scss;
- to use our variables, mixins and bootstrap mixins just add `@import "../helpers/helpers";` line at the top of your *page*.scss.

### Responsive

While using breakpoints we should use right order of its placement:

* Correct order of breakpoints in case from desktop view to mobile view:

```sass

@include media-breakpoint-down(xl) {
  // Extra large devices
}

@include media-breakpoint-down(lg) {
  // (max-width: 1199px)
}

@include media-breakpoint-down(md) {
  // (max-width: 991px)
}

@include media-breakpoint-down(sm) {
  // (max-width: 767px)
}

@include media-breakpoint-down(xs) {
  // (max-width: 575px)
}

```

* Correct order of breakpoints in case from mobile to desktop view:

```sass

@include media-breakpoint-up(xs) {
  // (max-width: 575px)
}

@include media-breakpoint-up(sm) {
  // (max-width: 767px)
}

@include media-breakpoint-up(md) {
  // (max-width: 991px)
}

@include media-breakpoint-up(lg) {
  //  (max-width: 1199px)
}

@include media-breakpoint-up(xl) {
  //  Extra large devices
}

```

* In case of pointing some exact breakpoint it can be used in random order and has prefix (only):

```sass

@include media-breakpoint-only(xs) {
  // (max-width: 575px)
}

@include media-breakpoint-only(sm) {
  // (min-width: 576px) and (max-width: 767px)
}

@include media-breakpoint-only(md) {
  // (min-width: 768px) and (max-width: 991px)
}

@include media-breakpoint-only(lg) {
  // (min-width: 992px) and (max-width: 1199px)
}

@include media-breakpoint-only(xl) {
  // (min-width: 1200px)
}

```

* Preferable way is to use one way of breakpoints direction: -up or -down, and to use them both only in exceptional cases"

* -only breakpoints should be placed only after group of -up or -down


## Js

... to be added

## Fonts

... to be added

## Data

Common data can be put into `src/data/data.json` file.

## Gitflow

Main develop branch - develop :)

For each task new branch must be created from 'develop' branch.
Branches naming convention:
```
for pages - page_page-name;
for components - c_component-name.
```

When you finish your task, you must create merge request, assign it to Andrii and add all front-end team via comment in description.
**Note:** `[WIP]` or `WIP` prefix could be added to MR title. There is short explanation about [GitLab WIP status](https://about.gitlab.com/2016/01/08/feature-highlight-wip/).

## Linting

To lint **scss** we use [Sass Lint](https://github.com/sasstools/sass-lint) withing [gulp-sass-lint](https://www.npmjs.com/package/gulp-sass-lint) plugin.
There is a gulp task `css:lint` that checks scss source code and show errors and warnings.
Rules configuration file `.sasslintrc` is located in the root directory and contain some rewrites of default sass lint rules.

## Design

Design located
mockups - https://epam.invisionapp.com/d/main/#/projects/prototypes/13162331
visual - https://epam.invisionapp.com/d/main/#/projects/prototypes/13168469

## Checkout-pages sticky functionality activation
For activation sticky functionality in checkout-right-aside, please do next steps:
1) please wrap right aside content by <div class=“right-aside-sticky”></div>;
2) if page contains "recently viewed" component, please wrap it by <div class="footer_sticky-right-aside">

## Husky pre-commit lint
To configure pre-commit lint run:
```
yarn setup:husky
```
