Skip to content

Latest commit

 

History

History
282 lines (200 loc) · 13 KB

README.md

File metadata and controls

282 lines (200 loc) · 13 KB
Raw

ANYWAY

deploy-development CI

ANYWAY: Newsflash InfoGraphics

Table of Contents

  1. About the project
  2. Want to help?
    1. Diving in
    2. Technical Overview for Developers
    3. 3nd party libraries
    4. Project directory structure
    5. Contribution Guidelines
  3. Server code
  4. Server API
  5. Environments and CI/CD
  6. Bundle size
  7. Git Scripts
  8. VScode & prettier
  9. Available Scripts

About this project:

Learn more about our Vision

Want to help?

  • Found a bug? feel free to open file a bug report. If you're new to github - see our How To step by step tutorial. You can also contact use on email or slack(see below)
  • Want contribute some code, help with our UI or improve documentation? Excellent! Please follow these steps

First thing first

  • Contact us - email would be great :) [email protected]
  • After we've got your mail, you'll able to join our Slack Channel. For any issues - contact Yuval or Atalya to get invitation.
  • Optional: install ZenHub, so you can see our project board.

Diving in

  • For improving documentation:
    • see issues marked as documentation and contact Yuval for guidance
    • This is a good summary for things to keep in mind when writing technical docs
  • For feature development, bug fixing etc:
  • If you have any question - feel free to contact Yuval or Atalya from AnyWAY Project

Technical Overview for Developers

This project was bootstrapped with Create React App. You can learn more in the Create React App documentation.

It is following Atomic Design guidelines with the following changes:

  • There are no "Organisms" components.
  • Atoms and Molecules are not state-aware (do not know MobX store exist)
  • Templates and Pages are state-aware
  • Molecules may contain other Molecules or Atoms. Atoms does not contain other Atoms.
Map keys

We use different google maps API keys for different environment. Staging / Production key are limited to our domain, and included in the repo .env.production. For using the map in development, You'll need to use a different key.

Steps:

  1. Get development API key from frontend team leader / dev advocate
  2. create a file named .env.local in your root directory (next to .env)
  3. Set key-value in the following format:
GOOGLE_MAP_KEY='THE_API_KEY_HERE'

3rd Party libraries included:

Also,to upload google maps API script for the street view component, the 'react-async-loader' library was used as described in https://github.com/edmund-dev/react-async-loader/blob/master/example/GoogleMap.jsx.

Project directory structure 

.
+-- assets          // images, icons, audio etc.
+-- components      // internal components (anything other than page component)
|   +-- atoms
|   +-- molecules
|   +-- organisms
+-- hooks           // common reusable hooks
+-- models          // typescript interfaces and classes
+-- pages           // page components
+-- services        // REST API, websocket, storage etc.
+-- store           // MobX stores
+-- style           // css-in-js code and wrappers
|   +-- _globals.ts // sizes, colors etc. - can be divided as project grow
|   +-- theme.ts
+-- utils
+-- App.tsx
+-- index.html
+-- index.css      // global styles (like fonts or reset/normalize css code)

Contribution Guidelines

Code Guidelines

Can be found in a separate file. Check them out here

Branch naming

Branch naming convention is as following

TYPE-ISSUE_ID-DESCRIPTION

examples:
feat-113-add-newsflash-location-on-map
fix-114-newsflash-location-not-accurate
PR naming

Pull Request (PR) title convention is as following

[TYPE-ISSUE_ID]-DESCRIPTION

example:
[Feat-113] Add newsflash location on map
[Fix-114] Newsflash location not accurate

When TYPE can be:

  • feat - is a new feature
  • doc - documentation only changes
  • cicd - changes related to CI/CD system
  • fix - a bug fix
  • refactor - code change that neither fixes a bug nor adds a feature

All PRs must include commit message with the changes description!

Branching system: master - used for production
dev - anything else
* For the initial start, Use git clone command to download the repository to your computer (With write privileges there is no need to fork the repo)

Creating a PR

A standard procedure for working on an issue would be to:

  1. git pull dev
  2. Create new branch from dev , like: refactor-137-making-pie-chart-generic-component
  3. Work - commit - repeat
  4. Git pull at dev
  5. On your branch: git merge dev and solve conflicts if they exist
  6. Push branch and open PR to dev.
  7. Get a code review approval / reject
  8. After approval, merge your PR
  9. GitHub will automatically delete the branch, after the merge is done. (they can still be restored).

If you never opened a PR on github - see our How To step by step tutorial

Server code

We have app server (written in express, a node.js-based framework) which supports 2 functions:

  • Cache API requests (from the backend data cluster)
  • Provide user management capabilities Our server repo

Server API

See API document

Environments and CI/CD

Active Environments:

  • Staging - to be used internally by Anyway teams
  • Production - Contains ready cards
  • Demo - Contains ready cards & Demo Cards
  • Mock - to be used to get demo mock information.

Environment base file is .env. Each environment has a specific environment file which can be used to override .env. for example .env.demo will override .env for Demo environment. For more info see CRA docs and this post about env-cmd

We use github actions for the following flows:

  1. on-push CI - provide per-PR CI testing and a live PR preview (see below)
  2. deploy-dev: continuous deployment of dev branch to Staging Environment - https://anyway-infographics-staging.web.app/
  3. deploy-master: continuous deployment of master branch to Production Environment:
  1. [Deprecated] deploy-demo: continuous deployment of demo branch to Demo Environment - https://anyway-infographics-demo.web.app/

Live Preview Once you open a PR and all test pass successfully, a temporary live preview site will be created. Use it to see the changes and make sure everything works, before asking for a code review.

You can get the live preview url by pressing "Show all Checks" and than "Details" on the main PR page. After clicking on "Details", the github action steps will be displayed. you can find the preview url under "Deploy" step (see image).

About bundle size

Since Create React App uses webpack under the hood, You can safely use named imports when working with Material UI components.

Git Scripts

Git scripts include in package.json to make working with git easier:

  • git:prune - Remove tracking branches no longer on remote (run it around once a week)
  • git:merged - Lists branches that have been merged into dev

VScode & prettier

Our package.json already include prettier section. If you have your own settings for VScode prettier extension, make sure to use the project config.

We use singleQuote as default. If having trouble with making the VScode extension use single quotes, please use the following config:

{
  "prettier.jsxSingleQuote": true,
  "javascript.preferences.quoteStyle": "single",
  "typescript.preferences.quoteStyle": "single",
  "prettier.singleQuote": true
}

Available Scripts

In the project directory, you can run:

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

npm test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

npm run build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

npm run sb

Run storybook locally.