README.md 6.12 KB
Newer Older
1
# What's Open
Tyler Hallada's avatar
Tyler Hallada committed
2

3
[![build status](https://git.gmu.edu/srct/whats-open/badges/master/build.svg)](https://git.gmu.edu/srct/whats-open/commits/master) [![coverage report](https://git.gmu.edu/srct/whats-open/badges/master/coverage.svg)](https://git.gmu.edu/srct/whats-open/commits/master) [![python version](https://img.shields.io/badge/python-2.7-blue.svg)]() [![Django version](https://img.shields.io/badge/Django-1.10-brightgreen.svg)]()
Tyler Hallada's avatar
Tyler Hallada committed
4

5
6
7
The What's Open project is an initiative at George Mason University by Mason
Student Run Computing and Technology (SRCT) to display which dining locations
are currently open on George Mason University's campus.
8

9
10
This repo is a simple Django Rest Framework (DRF) project that contains the
database backend and API for SRCT developed What's Open applications. 
Tyler Hallada's avatar
Tyler Hallada committed
11

12
13
14
15
What's Open needs all the help it can get. Even if you don't feel 
like you can be helpful with the heavily technical aspects, 
we definitely need designers and technical writers.
 
16
There are many things that can be done with this project (see the project [Issues](https://git.gmu.edu/srct/whats-open/issues) 
17
18
section), but sometimes it's the small things that count, so don't be afraid of 
contributing just for a spelling mistake.
Tyler Hallada's avatar
Tyler Hallada committed
19

20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
If you need help at all please contact any SRCT member in the `#whats-open` 
channel in our [slack group](https://srct.slack.com). We want people to contribute, so if you are struggling, or just want to 
learn, then we are willing to help.

# Setup instructions for local development

What's Open currently supports developers on Linux and macOS systems. Here's our 
walk-through of steps we will take:

1. Install `git` on your system.
2. Clone the whats-open codebase.
3. Get whats-open up and running with the method of your choice.

## 1) Install `git` on your system.

`git` is the version control system used for SRCT projects.

### On Linux Based Systems

**with apt:**

Open a terminal and run the following command:

    sudo apt update

This retrieves links to the most up-to-date and secure versions of your packages.

Next, with:

    sudo apt install git

you install `git` onto your system.

**with pacman:**
  
    pacman -S git

### On macOS

We recommend that you use the third party Homebrew package manager for macOS,
which allows you to install packages from your terminal just as easily as you
could on a Linux based system. You could use another package manager (or not
use one at all), but Homebrew is highly reccomended.

To get homebrew, run the following command in a terminal:

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)

**Note**: You do NOT need to use `sudo` when running any Homebrew commands, and
it likely won't work if you do.

Next, to make sure Homebrew is up to date, run:

    brew update

Finally we can install git with:

    brew install git

## 2) Clone the whats-open codebase

Now, we're going to clone down a copy of the whats-open codebase from [git.gmu.edu](http://git.gmu.edu/srct/whats-open),
the SRCT code respository with SSH.

**a)** Configure your ssh keys by following the directions at:

[git.gmu.edu/help/ssh/README](http://git.gmu.edu/help/ssh/README).

**b)** Now, on your computer, navigate to the directory in which you want to download the project (ie. perhaps one called `development/SRCT`), and run

    git clone git@git.gmu.edu:srct/whats-open.git

## 3) Get whats-open up and running

#### Prerequisites & Required Packages

First, install python, pip, and virtualenv on your system.
  * `python` is the programming language used for Django, the web framework used by whats-open.
  * `pip` is the python package manager.
  * `virtualenv` allows you to isolate pip packages within virtual environments

Open a terminal and run the following command:

    sudo apt update

Next, with:

    sudo apt install python python-dev python-pip
    sudo pip install virtualenv

you install `python`, `pip`, and `virtualenv`.

Next with,

    cd whats-open/
    virtualenv venv
    source venv/bin/activate
    pip install -r requirements.txt
    python manage.py makemigrations
    python manage.py migrate

you setup the project.

# Running the local web server
Tyler Hallada's avatar
Tyler Hallada committed
124

Tyler Hallada's avatar
Tyler Hallada committed
125
126
Now that everything is set-up you can run the server on your computer.

127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
    python manage.py runserver

Go to [http://127.0.0.1:8000/]() in your browser and you should see the website. 

Initially, there won't be any restaurants showing. You will need to add them to 
the database. 

Run,

    python manage.py createsuperuser

to create a superuser to use when signing in to the admin interface. 

Go to [http://127.0.0.1:8000/admin/]() to add new Restaurant and Schedule objects 
to your database.
Tyler Hallada's avatar
Tyler Hallada committed
142

143
With that, everything should be good to go!
Tyler Hallada's avatar
Tyler Hallada committed
144

145
# Modifying and Deploying Code
Tyler Hallada's avatar
Tyler Hallada committed
146
147
148
149
150
151

With the means of testing the website, you can really start contributing.

If you're new to Django and don't know where to start, I highly recommend
giving the [tutorial](https://docs.djangoproject.com/en/dev/intro/tutorial01/)
a try. However, it leaves out a lot of important things, so remember, Google is
152
your friend.
Tyler Hallada's avatar
Tyler Hallada committed
153

154
155
156
157
For the JavaScript, I will be using jQuery whenever possible because I prefer
it to straight up JavaScript. jQuery has [great
documentation](http://docs.jquery.com/) and I've found [Mozilla's documentation
on JavaScript](https://developer.mozilla.org/en-US/docs/JavaScript) to be
158
useful as well. But if your Google-fu is sharp, that should suffice.
159

160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
## CONTRIBUTING.md

This document goes into detail about how to contribute to the repo, including 
guidelines for commit messages and details on the workflow of the project.

## Opening issues

There are templates for issue descriptions located on the new issue page. I will
close issues with poor descriptions or who do not follow the standard.

## Coding style

You should adhere to the style of the repo code. Consistancy is key! PEP8 
guidelines are strongly reccomended but not enforced at the time. Please comment your code, I will not accept commits that contain uncommented code.

## Getting Help

I encourage you to join the [#whats-open channel](https://srct.slack.com/messages/go/details/) in SRCT's [Slack Group](https://srct.slack.com)
if you have any questions on setup or would like to contribute.