Commit 110bf730 authored by David Haynes's avatar David Haynes 🙆
Browse files

Merge branch '15-README-redo' into 'upgrade-django'

docs: Overhaul README and modernize language

See merge request !10
parents c92d6c27 4a4a8ae7
What's Open
===
# What's Open
Simple Django site displaying which dining locations are currently open on
George Mason University's campus.
[![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)]()
For more up-to-date information, view the [What's Open
wiki page](http://wiki.srct.gmu.edu/wiki/index.php/Whatsopen).
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.
Contributing
---
UPDATE:
Please join the #whats-open channel at srct.slack.com in order to chat with project
members about how to contribute. There are pinned posts in the sidebar of that channel
containing step by step instructions about how to get setup in addition to info about
branches and the direction of the project.
Thanks!
OUTDATED:
This repo is a simple Django Rest Framework (DRF) project that contains the
database backend and API for SRCT developed What's Open applications.
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.
There are many things that can be done with this project (see the "To Do"
There are many things that can be done with this project (see the project [Issues](https://git.gmu.edu/srct/whats-open/issues)
section), but sometimes it's the small things that count, so don't be afraid of
contributing just for a spelling mistake.
If you need help at all please contact any SRCT member. We want people to
contribute, so if you are struggling, or just want to learn, then we are willing
to help.
Set Up
---
To get started, you'll need the following installed:
* [Python 2.7](http://www.python.org/download/)
* [Django 1.5 or later](https://www.djangoproject.com/download/)
* [Git](http://git-scm.com/book/en/Getting-Started-Installing-Git)
* [virtualenv](http://www.virtualenv.org/en/latest/index.html#installation)
(to install you will need either
[pip](http://www.pip-installer.org/en/latest/installing.html) or
[easy_install](http://pythonhosted.org/distribute/easy_install.html))
Then type the following commands in your terminal (if you're on Windows,
[Cygwin](http://www.cygwin.com/) is recommended).
```bash
git clone http://git.gmu.edu/srct/whats-open.git
cd whats-open/
virtualenv venv --distribute
source venv/bin/activate
pip install -r requirements.txt
python manage.py syncdb
python manage.py migrate website
```
More detailed info on installation can be found on the [SRCT
wiki](http://wiki.srct.gmu.edu/wiki/index.php/Whatsopen#Installation)
Running the Site Locally
---
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
Now that everything is set-up you can run the server on your computer.
```bash
python manage.py runserver
```
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.
Go to http://127.0.0.1:8000/ in your browser and you should see the website.
Though, there won't be any restaurants showing. You will need to add them to
the database. Go to http://127.0.0.1:8000/admin/ to add new Restaurant and Schedule
objects to your database (the login would be the same username and password you
entered when creating a superuser during the `python manage.py syncdb` command).
With that, everything should be good to go!
Modifying and Deploying Code
---
# Modifying and Deploying Code
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
your friend. If you can't figure it out there, ask me.
your friend.
For the JavaScript, I will be using jQuery whenever possible because I prefer
it to straight up JavaScript. jQuery has [great
......@@ -92,44 +157,22 @@ documentation](http://docs.jquery.com/) and I've found [Mozilla's documentation
on JavaScript](https://developer.mozilla.org/en-US/docs/JavaScript) to be
useful as well. But if your Google-fu is sharp, that should suffice.
Once you actually make your changes and have fully tested them you can push the
code to the git repository. The best way to do this is to fork the project, make
the changes in your local repository, push to gitlab, and submit a pull request.
There are many ways to use git, and this is one example:
```
git commit -a
git push origin master
```
Some more helpful links on how to use Git:
* [Git Reference](http://gitref.org/)
* [OpenHatch's Training Mission](https://openhatch.org/missions/git)
* [Visual Git
Reference](http://marklodato.github.com/visual-git-guide/index-en.html)
* [Git For Ages 4 And
Up](http://blip.tv/open-source-developers-conference/git-for-ages-4-and-up-4460524)
To Do
---
* Get all restaurants displaying correct open times on the page. AKA. make
extensive tests.
* Sort by location view
* Add times until opening/closing for restaurants that are close, and exact
times for those that aren't.
* Make page refresh, or more preferably have the data refresh. For
example, with AJAX calls.
* Create more useful API calls. Document them.
* Allow switching between campuses. In the database, mark which campus each
restauraunt is on, include this information in the JSON object returned at
`ajax/schedule` and store the campus choice in the user's cookies
so that when they come back the page will already be set to their campus.
Default would be Fairfax of course.
[jquery-cookie](https://github.com/carhartl/jquery-cookie) would be useful
for this.
* What's open for everything on campus, not just campuses-- for the card office, library, gyms, tutoring centers, places off campus that accept Mason Money
* I'm seeing an "IndexError: list index out of range" that doesn't apparently affect anything being tossed in the managepy output
## 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.
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