Skip to content

GitLab

Commit f4ace873 authored by Andrew Hrdy's avatar Andrew Hrdy
Browse files

Updated README

parent 546ee664
Hide whitespace changes
Inline Side-by-side
README.md
View file @ f4ace873
......@@ -5,18 +5,242 @@ the [What's Open API](https://git.gmu.edu/srct/whats-open) to display informatio
George Mason University's campuses.
## Contributing
- Join `#whats-open-web` on [slack](https://srct.slack.com)
- Tag a fixed issue within the commit by ending the commit with `closes #issue`
- Open issues can be found [here](https://git.gmu.edu/srct/whats-open-web/issues)
What's Open Web is a mature project; however, there are still new features to add and bugs to fix.
A list of issues can be found [here](https://git.gmu.edu/srct/whats-open-web/issues). When you finish
an issue, please end the commit with `close #issue_number`. This will automatically link the issue
with the commit.
### Requirements
- [git](https://git-scm.com/)
- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)
If you need any help, feel free to contact us in the `#whats-open-web` channel of our
[Slack](https://srct.slack.com/).
### Setup
1. Clone the repository
2. Install dependencies either by `npm install` or `yarn`
A list of languages, frameworks, and tools used in this projects can be found below. See the associated
links for tutorials.
### Debugging
- A development server can be accessed by `npm start` or `yarn start`
- It is highly recommended to use the React and Redux dev tools
\ No newline at end of file
- Very basic understanding of HTML, JavaScript, CSS
- Typescript - [Documentation](https://www.typescriptlang.org/docs/home.html)
- React - [Getting Started](https://reactjs.org/docs/getting-started.html)
- Redux - [Getting Started](https://redux.js.org/introduction/getting-started)
- Redux Saga - [Documentation](https://redux-saga.js.org/)
- Material-Ui - [Documentation](https://material-ui.com/getting-started/usage/)
- SaSS - [Documentation](https://sass-lang.com/documentation)
You most likely will not need to know about the following technologies as they are for more advanced parts
of the application (e.g. the building phase).
- Webpack - [Documentation](https://webpack.js.org/concepts/)
- Service Workers - [Introduction](https://developers.google.com/web/fundamentals/primers/service-workers)
- Progressive Web Applications - [Summary](https://developers.google.com/web/progressive-web-apps)
- Workbox - [Documentation](https://developers.google.com/web/tools/workbox/reference-docs/latest)
## Setup Instructions
### Install Git / Clone the Repository
- Follow the directions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
for your operating system.
- Open a terminal, navigate to the directory where you want to store `whats-open-web` and run
`git clone git@git.gmu.edu:srct/whats-open-web.git`
### Install node and npm
#### Windows
Download and run the installer found [here](https://nodejs.org/en/).
#### MacOS
Run `brew install node` in a terminal.
### Installing devtools
These browser extensions allow you to more easily debug your code.
It is recommended to use Chrome to develop as it has the best developer tools.
Firefox's developer tools are also good, do not use Safari.
- React Developer Tools - [Chrome Web Store](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi)
- Redux DevTools - [Chrome Web Store](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en)
### Installing dependencies
Project dependencies are managed using npm. To install all the dependencies, run `npm install`
from the directory you cloned the project into.
### Installing ngrok (optional)
In order to test `whats-open-web` on a mobile device, ngrok will create a tunnel to your localhost,
allowing anyone to securly connect to it without needing to do any port forwarding on your router.
To install ngrok, create an account for free and follow the instructions [here](https://ngrok.com/).
Once you have installed ngrok, navigate to the following file (or create it if it does not exist):
Windows: `C:\Users\example\.ngrok2\ngrok.yml` <br/>
Linux: `/home/example/.ngrok2/ngrok.yml` <br/>
MacOS: `/Users/example/.ngrok2/ngrok.yml` <br/>
In this file, copy the following on the line after `authtoken`
```
tunnels:
react:
proto: http
addr: 3000
host_header: "localhost"
```
In any terminal, run `ngrok start react` to create a secure tunnel to `localhost:3000`
## Debugging
A development server can be started by using `npm install` and can be accessed by navigating
to `localhost:3000` in your browser. If you are planning to debug on a mobile device, follow
the steps above to install ngrok. Once in the browser, the current state of the redux store
can be accessed by using the `Redux Devtools` extension. The state of any React component can
be accessed by using the `React Developer Tools` extension.
If you need to stepthrough the Javascript, it is reccomended to use a IDE that can connect to
the browser instead of stepping through the code on the browser. The following instructions
are to do this with Visual Studio Code and Chrome:
- Install Visual Studio Code [here](https://code.visualstudio.com/).
- Open `whats-open-web` in Visual Studio Code.
- On the left side of the window, press the extensions icon and install the
`Debugger for Chrome` extension.
- Navigate to `./vscode/launch.json` found in your `whats-open-web` directory. If the file
does not exist, create it.
- Copy the following configuration into this file:
```
{
"version": "0.2.0",
"configurations": [
{
"type": "chrome",
"request": "launch",
"name": "Launch Chrome against localhost",
"url": "http://localhost:3000",
"webRoot": "${workspaceFolder}"
}
]
}
```
- Place a breakpoint on the line in the file where you want to debug. This is done
by clicking on the left column of the text editor on the line.
- Navigate to the `Debug` option in the menu bar and select `Start Debugging`.
(**Important:** The development server must first be started using `npm run start`)
- A new chrome window will open which will correctly stop on breakpoints placed in visual studio code.
## Architecture
This section explains the project structure in more detail. Instead of reading this section, feel
free to ask any questions you may have in our Slack channel as most of this information is not
needed for new contributors.
From the top level, there are three directories of importance, `/public`, `/src` and `/webpack`.
### /public
This directory contains the `index.html` file which is the entry point of our application. When the
application loads, React will be injected into the `<div id="root"></div>` tag. Any head tag
(e.g. OpenGraph tags) should be placed in this file. This directory also contains our Progresive
Web Application `manifest.json` file and the websites favicion. Code should not be added to this directory.
### /src
This directory contains all source files and anything non-build or entry related should be placed
here. This application is written in React and Redux. React components can be found in the
`/components` and `/containers` section. React components in the `/components` directory are to be
considered dumb and the only information given to them is via their props. React components in the
`/containers` directory are smart and may retrieve information from either their props or the
Redux store. With the introduction of hooks, we have moved away from using the traditional class
based React component. Now, all components are written as functions utilizing hooks. Please do not
create a class-based component as they are more complicated. All components are written using
TypeScript and it is important that strict type-checking is done. This minimizes the amount of
runtime errors. Please do **not** use the `any` type as it eliminates these benefits.
The `/models` directory contains the typing definitions for objects returned by the
[What's Open API](https://api.srct.gmu.edu/whatsopen/v2/). If the API is updated, pease update
these types to ensure proper typechecking.
The `/store` directory contains all Actions, Reducers, and Sagas for the Redux store. There are
three primary sections of the store - the alerts, facilities, and ui. An annotated structure of the store
is as follows:
```
{
facilities: {
facilities: IFacility[], // The list of facilities
isFetching: boolean // True if currently fetching the facilities; otherwise false
},
alerts: {
viewedAlerts: number[], // The ids of the alerts already viewed by this browser
alerts: IAlert[] // A list of currently active alerts
},
ui: {
search: {
searchTerm: string, // The string being searched
campusRegion: CampusRegion // The currently selected campus
},
favorites: string[], // The slugs of the facilities favorited by this browser
selectedFacility: string // The slug of the selected facility
}
}
```
It is important to note that the store is done using Redux, while Redux-Saga is the middleware
we are using. This allows for certain side-affects to occur based on specific dispatched
Actions. Some of the actions intercepted by Saga are to fetch the alerts and facilities and to
(un)favorite a facility.
We are using the `material-ui` library for styling. Even though this uses [JSS](https://cssinjs.org/?v=v10.0.4)
for styling, we have opted to instead use [SaSS](https://sass-lang.com). This decision was made
due to a lack of features in JSS and more familiarity with CSS. All of the .scss files can be found
in the `/styles` directory. This directory structure mimics that of the `/components` and `/containers`
to quickly associated components and their styling. The root stylesheets are `whatsOpen.scss` and
`whatsOpenMobile.scss` (**Note**: `whatsOpen.scss` should still be included in the mobile version, but
not vice-versa).
The `/utils` directory contains various utility files used throughout the project. The most notable
of these is `facility.util.ts`. This file contains all of the logic to properly handle the
facilities returned by the API. Some examples of logic are to find the facilities active schedule and
to determine whether the facility is open or closed.
`index.tsx` is the entry point for the React code and where all build files should be imported
(e.g. the root stylesheets). This file creates the `material-ui` theme using theming overrides
found in `theme.ts`. This theme will correctly adhere to a devices color scheme preference.
In addition, this file initializes the service worker and handles listening logic from
`workbox-broadcast-update`.
### /webpack
This directory contains the webpack configuration files used to build the application for both
development and production builds. Since both the development and production config files need
paths to the specific files, and loaders for every file type, `paths.js` and `loaders.js`
are used to centralize this logic.
The configuration for the development and production builds can be respectfully found in
`webpack.config.dev.js` and `webpack.config.prod.js`. The notable differences between
these files is that the production build minifies both the transcompiled JavaScript and
the CSS. In addition, the production build extracts the CSS to a separate file so it
is not bundled in the `<head>` section of the built html file. The production build also
builds using the service worker. Building a development build with the service worker
would cause confusion when debugging as cached content would be loaded. If you are planning
on debugging the service worker, add the `WorkboxPlugin.InjectManifest` plugin to the
development build. Finally, the development build starts a development server and does
not output any built files to the `/build` directory.
### Misc
The `.gitlab-ci.yml` file contains configuration information for our CI/CD processes on Gitlab.
There are two stages, the `build` and `deploy` stage. In the build stage, there are two options,
either `build` or `build_shopmason`. Build will build the application for deployment on
`whatsopen.gmu.edu` and `build_shopmason` will build the application to be given to shopmason.
The notable difference between these two is that the `API_GET_FACILITIES` build parameter, which
is the URL used to retrieve the facilities, is different. For deployment, `deploy_staging` will
automatically run whenever code is committed to the `development` branch, and `deploy_production`
must manually be triggered to deploy the code on the `master` branch.
As the name implies, `CHANGELOG.md` is our changelog and should be updated before every release.
`tslint.json` contains linting rules for TypeScript to ensure that all of our code conforms to
a standardized style.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment