Skip to content

Getting Started Guide

Jump to bottom
Sean Ye edited this page Mar 19, 2021 · 7 revisions

Getting Started Guide

Table of Contents

  1. Installation
  2. Linting
  3. Testing
  4. Building
  5. Pull Requests
  6. Pipeline
  7. Deployment
  8. Architecture

Installation

Install yarn if you haven't already.

yarn is a package manager like npm which we use to manage third party dependencies and run npm scripts in our package.json. Choosing yarn over npm is just a personal preference as yarn is generally a bit faster and more intuitive with commands and error messages.

Clone the repo to your machine:

git clone https://github.com/seanye24/cse110-w21-group6

Once you've cloned the repo, run yarn install to install the dependencies used in the project.

Linting

If you're unfamiliar with linting,

lint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors, and suspicious constructs. [4] The term originates from a Unix utility that examined C language source code | Wikipedia

We are using linters to help catch potential runtime errors and maintain good code quality.

We'll be using the following linters:

Domain Linter Configuration
JavaScript ESLint airbnb
CSS stylelint stylelint recommended
HTML HTMLHint Taken from wiki
Formatting Prettier some rules I like

Note: Prettier is a standalone code formatter, but we are using eslint-plugin-prettier to run Prettier as an eslint rule integrate formatting rules in our linting process. Also if you're curious, we're also using eslint-config-prettier to turn off all formatting related ESLint rules that might conflict with Prettier.

To lint your code, run yarn lint. Linting results will be displayed in the console. To autofix some of the linting errors, you can run yarn lint:fix to resolve some of the linting errors. Usually formatting errors are easily resolved, but usually programming errors will have to be fixed manually. See the npm scripts for more details.

Testing

We will be using Jest for testing all of our code functionality. By default, Jest looks for files ending in .test.js (and some other files, but we won't worry about that). For example, if you have feature called foo.js, you would write unit tests for it in tests/foo.test.js. We will be putting our tests in the src/tests directory. Jest runs tests in isolated environments, so don't worry about multiple tests affecting each other. Jest has a rich testing API, but generally your tests will be of the format:

test('test name', () => {
    // do something
    expect(calculatedValue).toBe(actualValue);
});

It is essential that you write unit tests for the most important and often used parts of your feature. Whether your tests are written before or after you write your code is up to you, but it is imperative that you write tests to ensure the quality and functionality of your code. Since we are practicing Agile, testing is a major part of the development process and what ultimately provides value to the CI pipeline.

Besides developers writing unit tests for their code, people should also write higher level functional tests, ideally by those who didn't write the functionality to reduce bias and provide a well-rounded evaluation. Functional tests are intended to test the product as a whole with common user actions (e.g adding a task, starting the timer) and could potentially include visual testing with tools like cypess.

For using Jest, I recommend reading: getting started and different matchers for expect.

To test your code, run yarn test. Testing results will be displayed in the console. Jest also provides code coverage reports (how robust your tests are) which are also displayed in the console and saved the coverage directory. See the npm scripts for more details.

Building

We are using webpack to build our code. Some of the things that webpack does automatically for us:

Webpack takes the new compiled files and places it into the dist (distributable) folder. You can see the specifics of our build process in the webpack config. In the end, our compressed bundle size is roughly half the size of our source code, so it helps a ton with performance! Webpack is a pretty complicated tool and I'm by no means an expert, so feel free to take a look and provide any suggestions.

Webpack is also important to our development process. We are using a single entry point and relying on webpack to generate the proper HTML file, so in order to test our changes, you must run yarn start. yarn start starts a local development server that serves your compiled code and will also listen for changes and efficiently update changes. You could also just run yarn build and serve the dist folder, but developing on the local dev server is much more convenient and faster with live reloading and HMR.

Another thing to note about the single entry point is that we are using src/index.js to be the entry point to all of our code. All JS modules must be imported through index.js or through any of the submodules. All other assets like .css stylesheets, images, web components, etc must be directly or tangentially imported by index.js in order to be included in the final build.

To build your code, run yarn build. To see and test the final build, run:

yarn global add serve
serve dist

Build results will be displayed in the console. See the npm scripts for more details.

Pull Requests

We will using GitHub pull requests as a way to run status checks and allow others to manually review code on feature branches before merging it into the main branch. Some guidelines:

  • Link the corresponding issue that it intends to solve using closing keywords
  • Write a short description of what the PR does and tries to fix. Mention any extra fixes or surprising things that weren't mentioned in the issue
  • Have at least 1 person review the request and approve it before merging with main branch
  • Assign yourself to the PR
  • Use appropriate labels (needs review, requires changes, ready to merge, etc)
  • Link the PR to the GitHub project

For reviewers, use this as an learning opportunity for yourself and the developer to give and receive honest and constructive feedback. Do not be mean and put others down for any errors or bugs. Try to use GitHub's code snippet selection feature to pinpoint specific lines of code.

Pipeline

We are using GitHub Actions to handle our continuous integration and continuous deployment. The workflows can be found at CI and CD.

Name Commands Runs on
CI yarn build, yarn lint, yarn test any push, any PR
CD yarn build, gh-pages, yarn docs push to main

Note: We are using this third party action which uses gh-pages to deploy our build to GitHub Pages. We are using this third party action to push our generated jsdoc docs into a jsdoc branch.

Deployment

We are hosting our app on GitHub Pages. The app can be found here.

Architecture

Our codebase uses a fairly structured MVC pattern with our components directory representing the view, scripts directory representing the controller, and models directory representing the model. Each script generally represents a corresponding component with the exception of controller.js which serves as the main controller and manages the event loop. Data usually flows in two directions, either component -> script -> model or model -> script -> component. Our data-flow follows the publish-subscribe pattern, where scripts will dispatch actions to the model and other components or scripts can subscribe to those actions and perform a local update based on which action is fired. scripts subscribe to the model using callbacks, and on actions, the model will fire those callbacks in a synchronous message queue fashion.

Still confused? Message me on Slack @Sean Ye and I'll do my best to try and explain it. If anything is incorrect, incomplete, or lacking, feel free to edit this document or message me and I'll try to add some more relevant documentation.

Clone this wiki locally