From 3ae0b0c0efd52817f71071ae1fa0bfff50f6ccd8 Mon Sep 17 00:00:00 2001
From: hojjat-fs <78338781+hojjat-fs@users.noreply.github.com>
Date: Mon, 30 Aug 2021 13:04:30 +0430
Subject: [PATCH] Sara|Hojjat / update readme (#6699)
* docs: update readme structure
* docs: update scripts doc
* docs: update other docs
* docs: update node version recommendation
* docs: update preview link
---
README.md | 130 +++++++++++++++++++++++++++------------
scripts/README.md | 65 ++++++++++++--------
src/javascript/README.md | 68 ++++++++++----------
src/sass/README.md | 52 +++++++++-------
src/templates/README.md | 130 +++++++++++++++++++++------------------
5 files changed, 269 insertions(+), 176 deletions(-)
diff --git a/README.md b/README.md
index 5c658e850b1de..2dfcfbcd43b19 100644
--- a/README.md
+++ b/README.md
@@ -1,110 +1,164 @@
-Binary-Static
-=============
+# Binary-Static
This repository contains the static HTML, Javascript, CSS, and images content of the [Binary.com](http://www.binary.com) website.
-## Installation
+   
-In order to work on your own version of the Binary.com Javascript and CSS, please **fork this project**.
+**In this document**
-You will also need to install the following on your development machine:
+- [Other Documents](#other-documents)
+- [Pre-installation](#pre-installation)
+- [Preview on your local machine](#preview-on-your-local-machine)
+- [Test link deployment](#test-link-deployment)
+- [Manage releases](#manage-releases)
+
+## Other Documents
+
+- [Scripts](scripts/README.md)
+- [Javascript](src/javascript/README.md)
+- [Sass](src/sass/README.md)
+- [Templates](src/templates/README.md)
+
+## Pre-installation
+
+Before running or contribute to this project, you need to have the setup of the following packages in your environment
- Ruby, RubyGems
- Sass (`sudo gem install sass`)
-- Node.js (10.14.2 or higher is recommended) and NPM (see )
-- Go to project root, then run `npm install`
+- Node.js (12.22.3 is recommended)
+- NPM (see )
- Grunt (`sudo npm install -g grunt-cli`)
-### Use a custom domain
-In order to use your custom domain, please put it in a file named `CNAME` inside `scripts` folder of your local clone of binary-static.
+## Quickstart
+
+1. **Fork the project**
+
+ In order to work on your own version of the Binary.com application, please fork the project to your own repo.
+
+2. **Clone using SSH**
+
+ ```sh
+ git clone git@github.com:your-github-username/binary-com.git
+ ```
+
+3. **Enter project directory**
+
+ ```sh
+ cd binary-com
+ ```
+
+4. **Install your dependencies:**
+ ```sh
+ npm ci
+ ```
-How to work with this project
-=============================
+5. **To start developing:**
-## Test link deployments
+ ```sh
+ npm run start
+ ```
+
+6. **Open the source code and start editing!**
+
+ Your site is now running at [https://localhost:443](https://localhost:443)
+
+## Preview on your local machine
+
+- To preview your changes locally, run `sudo grunt serve`
+- It will watch for Javascript or CSS changes and will rebuild on every change you make.
+- To test changes made to templates, you need to re-compile them:
+ - `grunt shell:compile_dev` to re-compile all templates.
+ - `grunt shell:compile_dev --path=about-us` to re-compile only template(s) which serve about-us path in URL.
+- To fix eslint errors run `npm run eslint`
+
+## Test link deployment
There are two types of test link deployment preview:
1. Automatic deployment
-Upon creating PR, `vercel` (https://vercel.com/) will auto-generate test link inside the PR. you can use that to preview test link for the changes you have made.
+Upon creating PR, `Vercel` (https://vercel.com/) will auto-generate the test link inside the PR. you can use that to preview the test link for the changes you have made.
2. Manual deployments
You can manually deploy your test link using gh-pages with the following configurations:
+
### Deploy to your gh-pages for the first time
-1. Register your application [here](https://developers.binary.com/applications/). This will give you the ability to redirect back to your github pages after login.
-Use `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/logged_inws.html` for the Redirect URL and `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/redirect.html` for the Verification URL.
+1. Register your application [here](https://developers.binary.com/applications/). This will give you the ability to redirect back to your Github pages after login.
+ Use `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/logged_inws.html` for the Redirect URL and `https://YOUR_GITHUB_USERNAME.github.io/binary-static/en/redirect.html` for the Verification URL.
- If you're using a custom domain, replace the github URLs above with your domain.
+ If you're using a custom domain, replace the Github URLs above with your domain.
-2. In `src/javascript/config.js`: Insert the `Application ID` of your registered application in `user_app_id`.
- * **NOTE:** In order to avoid accidentally committing personal changes to this file, use `git update-index --assume-unchanged src/javascript/config.js`
+2. In `src/javascript/config.js`: Insert the `Application ID` of your registered application in `user_app_id`.
-3. Run `grunt dev`
+- **NOTE:** In order to avoid accidentally committing personal changes to this file, use `git update-index --assume-unchanged src/javascript/config.js`
+3. Run `grunt dev`
### Deploy js/css and template changes together
-```
+```sh
grunt dev
```
-
### Deploy only js/css changes
-```
+```sh
grunt deploy
```
-
### Deploy some template changes
-```
+```sh
grunt dev --path=about-us
```
-
### Using sub-folders
+
There are times that you are working on various branches at the same time, and you want to deploy/test each branch separately on your gh-pages, you can simply use `--branch=branchname` for grunt commands:
+
- `grunt dev --branch=branchname`
-This will deploy your changes to a sub-folder named: `br_branchname` and it can be browsed at: https://YOUR_GITHUB_USERNAME.github.io/binary-static/br_branchname/
+ This will deploy your changes to a sub-folder named: `br_branchname` and it can be browsed at: https://YOUR_GITHUB_USERNAME.github.io/binary-static/br_branchname/
In order to remove the created folders from your gh-pages, you can use either:
+
- `grunt dev --cleanup`: removes all `br_*` folders and deploys to the root folder.
or
+
- `grunt shell:remove_folder --folder=br_branchname1,br_branchname2,...`: only removes the specified folder(s) from your gh-pages.
or
+
- `grunt shell:remove_folder --keep --folder=br_branchname1,br_branchname2,...`: only keeps the specified folder(s) on your gh-pages and removes everything else. Just add the `--keep` flag.
-## Preview on your local machine
-- To preview your changes locally, run `sudo grunt serve`
-- It will watch for js/css changes and rebuild on every change you make.
-- To test changes made to templates, you need to re-compile them:
- - `grunt shell:compile_dev` to re-compile all templates.
- - `grunt shell:compile_dev --path=about-us` to re-compile only template(s) which serve about-us path in URL.
-- To fix eslint errors run `npm run eslint`
+### Use a custom domain
-## Release
+In order to use your custom domain, please put it in a file named `CNAME` inside `scripts` folder of your local clone of binary-static.
-```
+## Manage releases
+
+```sh
git tag ${RELEASE_TARGET}_vYYYYMMDD_${INTEGER} -m 'some message'
```
> `RELEASE_TARGET` could be one of **staging** or **production** for staging and production release respectively.
-Example:
+Example:
-```
+```sh
git tag production_v20191010_0 -m 'release fixes to production'
```
Push the tag:
-```
+```sh
git push origin staging_v20191010_0
```
+
+## Manage translations
+
+- Automatic: this will be done automatically with [Github action](.github/workflows/sync_crowdin_translations.md)
+- Manual: If you need to add translation manually use [manual translation doc](scripts/README.md#Updating-the-translations)
diff --git a/scripts/README.md b/scripts/README.md
index 9612b347df64e..0fe5c12c4ede1 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -1,54 +1,67 @@
+# Scripts
+
+**In this documents**
+
+- [Updating the Translations](#updating-the-translations)
+- [Updating the Sitemap](#updating-the-sitemap)
+
## Updating the Translations
### Initial setup:
-* Please make sure you have done `npm install`.
-* Install `Homebrew` by `ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
-* Install and follow the instructions here: https://support.crowdin.com/cli-tool/#installation
-* **Important:** Please use version 3 of the crowdin cli-tool
-* Get [Crowdin API Key](https://crowdin.com/project/binary-static/settings#api) and add this line to your _.bash_profile_: `export CROWDIN_API_KEY='put API Key here'`
-**IMPORTANT!** This key gives full access to all your Crowdin project data. Treat this just like a password and never push it to any public repo.
+
+- Please make sure you have done `npm install`.
+- Install `Homebrew` by `ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
+- Install and follow the instructions here: https://support.crowdin.com/cli-tool/#installation
+- **Important:** Please use version 3 of the crowdin cli-tool
+- Get [Crowdin API Key](https://crowdin.com/project/binary-static/settings#api) and add this line to your _.bash_profile_: `export CROWDIN_API_KEY='put API Key here'`
+ **IMPORTANT!** This key gives full access to all your Crowdin project data. Treat this just like a password and never push it to any public repo.
### To update the translations:
-* Simply run `./scripts/update_translations.sh` in root folder of project to do these tasks:
-(It is possible to confirm/skip each task by answering y/n to questions, only first one is mandatory):
- * Check out and update the translations branch
- * Update master and merge into translations
- * Update the source file (messages.pot) and push to Crowdin
- * Download translation files from Crowdin to `src/translations` and update javascript texts `src/javascript/_autogenerated/[LangCode].js`
- * Commit changes and push to origin
- * Open github to submit the PR
+
+- Simply run `./scripts/update_translations.sh` in root folder of project to do these tasks:
+ (It is possible to confirm/skip each task by answering y/n to questions, only the first one is mandatory):
+ - Check out and update the translations branch
+ - Update master and merge into translations
+ - Update the source file (`messages.pot`) and push it to Crowdin
+ - Download translation files from Crowdin to `src/translations` and update javascript texts `src/javascript/_autogenerated/[LangCode].js`
+ - Commit changes and push to origin
+ - Open Github to submit the PR
### Extracting texts from js code:
+
Texts that are used in js code will automatically be extracted during the translation update process (3rd step above: Updating the source file).
In order to make sure that no strings are missed by the extractor code while pushing to translations, please:
1. Refactor the code so that the first argument passed to the `localize()` method is a string literal.
- i.e.
- ```js
- const text = localize(is_started ? 'Sell at market' : 'Sell');
- ```
- would change to:
- ```js
- const text = is_started ? localize('Sell at market') : localize('Sell');
- ```
+ i.e.
+ ```js
+ const text = localize(is_started ? 'Sell at market' : 'Sell');
+ ```
+ would change to:
+ ```js
+ const text = is_started ? localize('Sell at market') : localize('Sell');
+ ```
2. If there is no way to have the string literal in js code (i.e. API texts which are not translated), add them to `scripts/js_texts/static_strings_app.js`.
- Note: Regarding API texts, even if the string is translated automatically somewhere else we should still include it here to avoid missing it if that other string gets removed.
+ Note: Regarding API texts, even if the string is translated automatically somewhere else we should still include it here to avoid missing it if that other string gets removed.
3. At the end, when you're sure that a string has already been taken care of, just put this comment `/* localize-ignore */` right after the first argument of `localize()` call to ignore it from tests.
### `js_texts` folder contents:
+
```
js_texts:
├── extracted_strings_app.js
└── static_strings_app.js
```
-- `extracted_strings_app.js`: Contains extracted strings. It's for debugging purpose only and shouldn't be changed manually.
+
+- `extracted_strings_app.js`: Contains extracted strings. It's for debugging purposes only and shouldn't be changed manually.
- `static_strings_app.js` to handle those strings that don't exist in js code. e.g. API texts that are not localised, etc.
During the translation update process, the source file `messages.pot` will be updated with all texts from both the above files.
## Updating the Sitemap
-* List of paths to include in `sitemap.xml` is here: [config/sitemap_urls.js](config/sitemap_urls.js)
-* Once the paths are updated in the above file, run `./scripts/sitemap.js` or `grunt shell:sitemap` to generate new `sitemap.xml` files in `src/root_files` according to each section.
+
+- The list of paths to include in `sitemap.xml` is here: [config/sitemap_urls.js](config/sitemap_urls.js)
+- Once the paths are updated in the above file, run `./scripts/sitemap.js` or `grunt shell:sitemap` to generate new `sitemap.xml` files in `src/root_files` according to each section.
diff --git a/src/javascript/README.md b/src/javascript/README.md
index 8039d6ebff09a..f380be9f662b2 100644
--- a/src/javascript/README.md
+++ b/src/javascript/README.md
@@ -1,8 +1,14 @@
-JavaScript Guidelines
-=============
+# JavaScript Guidelines
+
+**In this document**
+
+- [General Guidelines](#general-guidlines)
+- [Style Guide](#style-guid)
+
+## General Guidelines
+
+In order to improve the clarity, quality, and development time it is worth considering the following principles whenever possible:
-### General Guidelines
-In order to improve the clarity, quality and development time it is worth considering the following principles whenever possible:
- [DRY (Don't Repeat Yourself)](https://en.wikipedia.org/wiki/Don't_repeat_yourself)
- [KISS (Keep It Simple, Stupid)](https://en.wikipedia.org/wiki/KISS_principle)
- [SoC (Separation of Concerns)](https://en.wikipedia.org/wiki/Separation_of_concerns)
@@ -11,7 +17,7 @@ In order to improve the clarity, quality and development time it is worth consid
---
-### Style Guide
+## Style Guide
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript/blob/master/README.md) is partially being followed in our code base.
@@ -23,38 +29,38 @@ In order to improve the clarity, quality and development time it is worth consid
**[Variables:](#naming-conventions-variables)** Variables should be lowercase words separated by `_`.
-
+
```js
const field_name = '...';
```
**[Functions:](#naming-conventions-functions)** Functions should be camelCase. This is to easily distinguish between variables and functions.
-
+
```js
const myFunction = () => { ... };
```
**[Modules:](#naming-conventions-modules)** Module names and classes should be PascalCase.
-
+
```js
const MyModule = (() => { ... })();
```
**[jQuery variables:](#naming-conventions-jquery-variables)** jQuery variables should have a `$` in the beginning to mark them.
-
+
```js
const $test = $('#test');
```
**[JavaScript elements:](#naming-conventions-javascript-elements)** JavaScript elements start with `el_` for a similar effect.
-
+
```js
const el_test = document.getElementById('test');
-```
+```
**[Boolean:](#naming-conventions-boolean)** Those variables which store a boolean value, should start with `is_`, `has_`, ...
@@ -69,9 +75,9 @@ const has_crypto = false;
```js
const fields = {
- txt_name : { id: '#txt_name' },
- chk_tnc : { id: '#chk_tnc' },
- ddl_agents: { id: '#ddl_agents' },
+ txt_name: { id: '#txt_name' },
+ chk_tnc: { id: '#chk_tnc' },
+ ddl_agents: { id: '#ddl_agents' },
};
```
@@ -88,17 +94,17 @@ const fields = {
**[API requests:](#commenting-api-requests)** Comments should be added to highlight logic that is hardcoded in the front-end and should move to API:
-- For changes that can be done in API V3, use the comment
-
- ```js
- // API_V3: [description of what needs to be moved to API]
- ```
+- For changes that can be done in API V3, use the comment
+
+ ```js
+ // API_V3: [description of what needs to be moved to API]
+ ```
-- For changes that should be done in API V4, use the comment
+- For changes that should be done in API V4, use the comment
- ```js
- // API_V4: [description of what needs to be moved to API]
- ```
+ ```js
+ // API_V4: [description of what needs to be moved to API]
+ ```
---
@@ -111,21 +117,21 @@ const fields = {
**[Align by equal:](#import-rules-align-by-equal)** Assignments are generally aligned by `=` for readability purposes.
```js
-const moment = require('moment'); // moment is an npm package
-const CookieStorage = require('./storage').CookieStorage; // our own function
+const moment = require('moment'); // moment is an npm package
+const CookieStorage = require('./storage').CookieStorage; // our own function
const applyToAllElements = require('./utility').applyToAllElements; // our own function
-const createElement = require('./utility').createElement; // our own function
-require('../../_common/lib/polyfills/array.includes'); // polyfill from lib folder
-require('../../_common/lib/polyfills/string.includes'); // polyfill from lib folder
+const createElement = require('./utility').createElement; // our own function
+require('../../_common/lib/polyfills/array.includes'); // polyfill from lib folder
+require('../../_common/lib/polyfills/string.includes'); // polyfill from lib folder
```
-**[Alphabetical ordering:](#import-rules-alphabetical-ordering)** The order is important; it should be sorted alphabetically according to path:
-
+**[Alphabetical ordering:](#import-rules-alphabetical-ordering)** The order is important; it should be sorted alphabetically according to the path:
+
- `moment` comes first as it's not a relative path.
- `s` is before `u` so `./storage` comes before `./utility`.
- Both `applyToAllElements` and `createElement` are from the same file, but `a` is before `c`
-- Unassigned `require` goes to the end
+- Unassigned `require` goes to the end
**[Combining require:](#import-rules-combining-require)** When there are many functions being imported from the same file, consider combining it into one import line.
diff --git a/src/sass/README.md b/src/sass/README.md
index 51c01ac3da477..c80f8db3956aa 100644
--- a/src/sass/README.md
+++ b/src/sass/README.md
@@ -1,14 +1,15 @@
-Sass Guidelines
-===============
+# Sass Guidelines
+
+## General Guidelines
+
+In order to improve the clarity, quality, and development time it is worth considering the following principles whenever possible:
-### General Guidelines
-In order to improve the clarity, quality and development time it is worth considering the following principles whenever possible:
- [Keep Sass Simple](https://www.sitepoint.com/keep-sass-simple/), which means [KISS (Keep It Simple, Stupid)](https://en.wikipedia.org/wiki/KISS_principle) may override [DRY (Don't Repeat Yourself)](https://en.wikipedia.org/wiki/Don't_repeat_yourself) in some cases
- [Single responsibility selectors](https://en.bem.info/methodology/css/#single-responsibility-principle)
---
-### Style Guide
+## Style Guide
- [Airbnb CSS / Sass Styleguide](https://github.com/airbnb/css/blob/master/README.md) is partially being followed in our code base.
@@ -24,8 +25,10 @@ In order to improve the clarity, quality and development time it is worth consid
**[Selectors:](#naming-conventions-selectors)** Selectors should follow the [BEM Two Dashes style](https://en.bem.info/methodology/naming-convention/#two-dashes-style): `block-name__elem-name--mod-name--mod-val`.
```scss
-.button {}
-.button--disabled {}
+.button {
+}
+.button--disabled {
+}
```
Remember to follow the [Single responsibility principle](https://en.bem.info/methodology/css/#single-responsibility-principle).
@@ -52,26 +55,31 @@ Keep all common variables in the [constants.scss](https://github.com/binary-com/
**[Flexibility:](#units-flexibility)** If flexibility is needed, for example for font-size, use units such as `rem`, `vh`, `vw`, `fr`, and only use `px` if it's supposed to be a fixed value.
-
#### When to use `em` and `px`?
+
- `em` is typically used in padding and margin to maintain the vertical rhythm. If a user resizes the text, the `em` unit will be scaled proportionately. `em` size is always relative to the font-size of the element.
+
```scss
// For example: `span` with font-size of 14px and padding of 8px.
// The padding in `em` should be `14px/8px * 1em ~ 0.571em`.
span {
- font-size: 1.4em;
- padding: 0.571em;
+ font-size: 1.4em;
+ padding: 0.571em;
}
```
+
- `px` is used to define a fixed value such as for `box-shadow`, `border-radius` and `border-width`.
#### Converts `px` to `em` values
+
1. Since the base font-size is set to be `10px = 1rem`, convert `px` to `em` by dividing the `px` value by 10.
+
```scss
.balloon {
- padding: 1.6em; // 16px;
+ padding: 1.6em; // 16px;
}
```
+
2. Or any online converter tool.
---
@@ -83,24 +91,24 @@ span {
```scss
@mixin link {
- color: $COLOR_WHITE;
+ color: $COLOR_WHITE;
- &:hover, &:active {
- text-decoration: none;
- }
+ &:hover,
+ &:active {
+ text-decoration: none;
+ }
}
.sidebar {
- background: $COLOR_LIGHT_GRAY;
+ background: $COLOR_LIGHT_GRAY;
- a {
- @include link;
- display: block;
- }
+ a {
+ @include link;
+ display: block;
+ }
}
```
-
---
### Commenting
@@ -109,4 +117,4 @@ span {
**[Explanations:](#commenting-explanations)** Feel free to add comments to explain any styling that is confusing.
-**[To do:](#commenting-todo)** Use `TODO: ...` comments anywhere that needs consideration or attention in the future.
+**[To do:](#commenting-todo)** Use `TODO: ...` comments anywhere that need consideration or attention in the future.
diff --git a/src/templates/README.md b/src/templates/README.md
index 4bfcc9d74ea86..756a0d49d7f13 100644
--- a/src/templates/README.md
+++ b/src/templates/README.md
@@ -1,93 +1,105 @@
-jsx Rules
-=============
+# Templates
+
+## Gerneral code style
- Use functional stateless components (`FSC`).
-- Use destructuring to capture parameters if needed.
+- Blocks need to have a single space after `{`, for example:
+
+```js
+{ array.map[() => ())}
+```
+
+## Rendering conditionally
+
- Use `{condition && ...}` syntax to conditionally render an element.
- Use `` tags inside a `
`). To bypass HTML escape, you can use `it.dangreouslyRenderHtml()` (under normal circumstances do NOT use this.):
+
+```js
+it.dangreouslyRenderHtml('');
+```
+
+## Props, arguments
+
- Do NOT use ``; just use ``.
+- Use destructuring to capture parameters if needed.
- Components with less than four arguments should stay list all in one line, for example:
-```
+```js
export const List = ({ items, id, className }) => (
-
- { items.length ?
-
- {items.map((item, idx) => )}
-
- :
- undefined
- }
-
-
+
+ {items.length ? (
+
+ {items.map((item, idx) => (
+
+ ))}
+
+ ) : undefined}
+
);
```
- Components with more than four arguments need to be broken down to separate lines, for example:
-```
+```js
export const Li = ({
- className,
- id,
- href,
- param = '',
- target,
- text,
- header,
- p,
+ className,
+ id,
+ href,
+ param = '',
+ target,
+ text,
+ header,
+ p,
}) => {
- const content = p ?
+ );
};
```
+## Import, Export
+
- Imports with four or more arguments need to be broken down to separate lines, but lower than that should stay in one line.
+
- Always name your components before default exporting them, for example:
-```
+```js
import React from 'react';
-const Loading = ({theme}) => (
-
);
export default Loading;
```
-- There are cases where you do not want your strings to be escaped (i.g. when you place `` tags inside a `
`). To bypass HTML escape, you can use `it.dangreouslyRenderHtml()` (under normal circumstances do NOT use this.):
-
-```
-it.dangreouslyRenderHtml('');
-```
-- Blocks need to have a single space after `{`, for example:
-
-```
-{ array.map[() => ())}
-```
+## Naming convention
- Functions should be named using CamelCase.
- Variable should be named using lower_case.