@@ -9,64 +9,97 @@ term maintenance. Additionally, since the core of the project is fairly simple,
2.0 functioned as a good introduction to open source development for new
members.
Go 3.0 is currently in production with the goal of modernizing the project with new functionality.
A project of [GMU SRCT](https://srct.gmu.edu).
## Architecture of the project
### `go_back`
`go_back` is the API backend of the project. It is built with the Django REST
Framework (python). It supports all CRUD (Create, Read, Update, Delete)
operations on Go links as well as RegisteredUser account management.
### `go_ahead`
### `go_ahead` | The react app
`go_ahead` is the ReactJS frontend of the project. It is built with the React
`go_ahead` is the react.js frontend of the project. It is built with the React
JavaScript framework to allow for rapid development and experimentation. There
is also a lot of interactivty that the framework allows that we can leverage
for a smooth user experience.
## Getting started with contributing
There's a workflow involved with getting started contributing but once you do
it once or twice it'll seem a lot less daunting.
1. Running `go_ahead` | React / Webpack
You'll need node installed.
```sh
npm install-g yarn
yarn
yarn dev
```
This starts a foreground process that will rebuild the React site whenever
there is a change.
2. Running `go_back` | Docker
### `go_back` | The django API
You'll need Docker and docker-compose installed.
In another terminal tab from the `yarn` one:
```sh
docker-compose up
```
3. Misc. | Actually coding
All JS changes will require a refresh (Webpack rebuilds the app in the background).
All Python changes will require a refresh.
To pull in python dependecies and work in a contained environment we use `pipenv`.
```
pipenv install
pipenv shell
```
4) Deployment of changes
See me.
`go_back` is the API backend of the project. It is built with the Django REST
Framework (python). It supports all CRUD (Create, Read, Update, Delete)
operations on Go links as well as account management.
## How to get up and running
As always, the first step is to get the project running on your local machine.
Consult the [docker documentation](https://docs.docker.com/install/) for instructions on how to install Docker CE and the [docker-compose documentation](https://docs.docker.com/compose/install/) on how to install Docker Compose.
Run:
```sh
docker-compose build
docker-compose up
```
Navigate to [127.0.0.1:8000](http://127.0.0.1:8000) after the compose process has finished running to access the app.
## How to contribute to the project
1. Go to [the issues page](https://git.gmu.edu/srct/go/issues) and look at what needs to be done, and have a cursory choice of something.
[React is a JavaScript library for building user interfaces.](https://reactjs.org/) The focus of the library is on component design and implementation.
I'll be the first one to admit that it is very daunting to jump into a React project if you are unfamiliar with the library, javascript, and general modern web developemnt trends. To help with that learning curve I have two suggested resources:
1.[A re-introduction to JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript) | A great start to reviewing JS and how you can translate knowledge from other languages into it.
1.[React Main Concepts](https://reactjs.org/docs/hello-world.html) | A step by step walkthrough of React, component architecture, and how you can best utilize the React API.
## React project structure
Take a chance to review the layout of the app:
```
src/
├── App.jsx | The entry point for our React app.
├── Components
│ ├── Molecules | All reusable components that are individual.
│ │ └── index.js
│ ├── Organisms | Containers for molecule components.
│ │ └── index.js
│ ├── Pages | Containers for organisms.
│ │ └── index.js
│ ├── Templates | Containers for pages.
│ │ └── index.js
│ └── index.js
└── Utils | Misc. standalone JS functions.
└── index.js
```
## Dev work
Since we will need to rebuild our app on a regular basis as we edit the javascript we need to start a process that watches the code and rebuilds the app.
You'll need [node installed](https://nodejs.org/en/download/package-manager/).
```sh
npm install-g yarn
yarn
yarn dev
```
This starts a foreground process that will rebuild the React site whenever
there is a change.
Make sure you are running this alongside the docker-compose process so that you can visit the site at [127.0.0.1:8000](http://127.0.0.1:8000)
All react errors are printed to the webpack console stdout.
Make sure to check your web browser's JS console as well!
If you have taken CS 112, you should be somewhat familiar with the fundamentals of Python. This is nice for building simple applications, but in the real world we utilize larger scale frameworks to help us with the heavy lifting for tasks such as building websites.
[Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.](https://www.djangoproject.com/) They designed the framework for to allow for rapid iteration, be secure by default, and scale outwards with ease.
It is necessary you become familiar with the concepts of the Django framework:
1. The [Django Overview](https://docs.djangoproject.com/en/2.1/intro/overview/) does a good job at highlighting specific components.
1. The [Django Rest Framework tutorial](https://www.django-rest-framework.org/tutorial/1-serialization/) walks through how to utilize Django components in building an API.
## The gist
1. Store data in models.
1. Extract data from models with serializers.
1. Present data with views.
1. Navigate to views with urls.
## Dev work
You will need to install the latest version of python 3.
```
pip install pipenv
pipenv install
pipenv shell
```
With docker-compose running the app, you can open a code editor to work on the API. All errors are printed to the docker console stdout.