Commit 16becd96 authored by David Haynes's avatar David Haynes 🙆

Compose all new documentation

- README fleshed out
- go_ahead / go_back documentation
parent c31a9907
Pipeline #3592 passed with stage
in 1 minute and 7 seconds
......@@ -8,7 +8,30 @@ in an open source repo.
**Note:**
You will need to be a member before making any contributions. Join the slack #go channel and ask nicely.
You will need to be **a member** before making any contributions. Join the slack #go channel and ask.
### Issues
Issues can be opened on gitlab and must adhere to the provided template:
```
# Summary
Here you should include two to three sentences explaining the thought process
about the current issue. Maybe a picture? Some details that could best help someone,
especially someone new, understand the goal of the issue and how they should best
approach the problem.
## Helpful Links
Here you should include a bullet point list of links to documentation, stack overflow,
whatever, that could help guide someone on what it is they are trying to do.
Essentially, a list of links to point them in the right direction.
```
Issues will be closed if they do not adhere to the standard.
You can claim issues by asking in the #go channel whether you can work on it. The project manager will then assign them to you in gitlab.
### Branches
......@@ -17,34 +40,39 @@ add, modify, or remove features/bugs from Go. Our list of tasks can be found on
the issues page.
If you decide to take on an issue for Go you will need to work in a branch off
of the current development branch (ie. `2.3-dev` with 2.3 being the version in
development).
of the current development branch (ie. `go-three`).
This can be done with the following chain of `git` commands within `go/`:
```sh
git pull
git checkout 2.3-dev
git checkout -B ##-shortdescription
```
**Note:**
Replace `##` with the issue number that you are working on, and replace
`shortdescription` with a few words (<=4) that in brief describe what the branch
`short-description` with a few words that in brief describe what the branch
does.
**Example:**
```sh
git pull
git checkout go-three
git checkout -B ##-short-description
```
**Example Workflow:**
```sh
git pull
git checkout 2.3-dev
git checkout -B 102-readmeUpdates
git checkout go-three
git checkout -B 102-readme-updates
```
If you are working on something that does not have an issue please open a new
issue before creating your branch.
Once you've written commits in a branch you will need to push your commits to gitlab.
git push origin ##-branchname
`origin` is gitlab.
### Commits & Their Messages
It is important to commit more often than not such that if we run into issues we
......@@ -54,7 +82,7 @@ Commit messages should follow the format:
#### Title -
Should fill in the blank:
Should fill in the blank (Don't actually write "This commit", just the part that comes after!):
This commit ______
......@@ -74,19 +102,13 @@ They don't have to be super serious (see any of my commits) though just a tad bi
Example commit description:
- mostly talk about how great SRCT (and :dhaynes:) is
- plus a short blurb on how we can ban you
- Composed a short blurb on how banning works
- Composed a description of SRCT
[Example full commit](https://git.gmu.edu/srct/go/commit/db89af2e4ffd06a6044d3301a3f7a45ced74799a)
### Merging to the current development branch
Once you've finished work in a branch you will need to push your commits to gitlab.
git push origin ##-branchname
`Origin` is gitlab.
Open a [merge request](https://git.gmu.edu/srct/go/merge_requests/new)
to start the process of getting your code into the repo. Your code wil be reviewed
by another member before being merged. Your code must pass our tests and include
......
......@@ -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.
1. Review [CONTRIBUTING.md](https://git.gmu.edu/srct/go/blob/go-three/CONTRIBUTING.md)
1. Review the documentation for individual components:
1. [`go_ahead` documentation](https://git.gmu.edu/srct/go/blob/go-three/go/go_ahead/README.md)
1. [`go_back` documentation](https://git.gmu.edu/srct/go/blob/go-three/go/go_back/README.md)
1. Get to the #go channel in SRCT Slack and ask for assistance.
## Other
- Make sure to ask any questions you have in the #go channel in SRCT Slack
- Go 3 logo was created by <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">Andres Villogas</a>
- Don't worry if nothing makes sense, we all start there.
- This project was made possible through the collective contributions of multiple Mason SRCT members:
<a href="https://git.gmu.edu/srct/go/milestones/3">Go 2.2</a>:
<br />
<a href="https://github.com/dhaynespls">David Haynes</a>,
<a href="https://github.com/ocelotsloth">Mark Stenglein</a>,
<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">
Andres Villogas
</a>
,<a href="https://github.com/IAmEyad">Eyad Hasan</a>,
<a href="https://github.com/zosman1">Zach Osman</a>,
<a href="">Leo Grandinetti</a>,
<a href="https://mason.gmu.edu/~gmoran/">Grady Moran</a>,
<a href="https://github.com/zmknox">Zach Knox</a>,
<a href="https://github.com/mike-bailey">Michael Bailey</a>,
<a href="https://github.com/jrouly">Michel Rouly</a>,
<a href="https://github.com/nanderson94">Nicholas Anderson</a>,
<a href="">Kevin Mckigney</a>, and
<a href="https://github.com/dwbond">Daniel Bond</a>.<br />
<a href="https://git.gmu.edu/srct/go/milestones/2">Go 2.1</a>:
<br />
<a href="https://github.com/dhaynespls">David Haynes</a>,
<a href="https://github.com/zosman1">Zach Osman</a>,
<a href="https://github.com/roberthitt">Robert Hitt</a>,
<a href="https://github.com/nanderson94">Nicholas Anderson</a>,
<a href="https://github.com/zmknox">Zach Knox</a>,
<a href="https://github.com/mike-bailey">Michael Bailey</a>,
<a href="https://github.com/mdsecurity">Mattias Duffy</a>,
<a href="https://github.com/IAmEyad">Eyad Hasan</a>, and
<a href="https://github.com/danielkim1">Danny Kim</a>.<br />
<a href="https://git.gmu.edu/srct/go/milestones/1">Go 2.0</a>:
<br />
<a href="https://github.com/dhaynespls">David Haynes</a>,
<a href="">Matthew Rodgers</a>,
<a href="https://github.com/nanderson94">Nicholas Anderson</a>, and
<a href="https://github.com/dwbond">Daniel Bond</a>.<br />
Go 1.0:
<br />
<a href="https://github.com/jrouly">Michel Rouly</a>,
<a href="https://github.com/creffett">Chris Reffett</a>,
<a href="https://github.com/nanderson94">Nicholas Anderson</a>, and
<a href="https://github.com/akshaykarthik">Akshay Karthik</a>.
<br />
# go_ahead
# go_ahead | The react app
Words on how to code in React.
[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!
# go_back
# go_back | The django API
Words on how to code on the go API.
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.
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