Merge pull request #63 from jakeharding/milestone-3

Milestone 3

CONTRIBUTING.md

@@ -1,5 +1,19 @@
 #### No external contributions are currently being accepted because this is a project for a university course.
 
+For existing contributors, please use the following header documentation at the top of each file:
+
+```
+fileName.ext - (C) Copyright - 2017
+This software is copyrighted to contributors listed in CONTRIBUTIONS.md.
+
+SPDX-License-Identifier: MIT
+
+Author(s) of this file:
+  Your name or github username
+
+Brief description of the file.
+```
+
 #### Guidelines
 - Always checkout a branch for developing. Never push to master or dev.
 - Write tests for all code written.

README.md

@@ -5,16 +5,7 @@
 
 This repository holds the proof of concept for the repository health and sustainability project for CSCI 4900 at the University of Nebraska at Omaha.  This repository will hold the backend and frontend source code to extract data from Github and ghtorrent and provide statistics about a selected repository.  Description of the backend and frontend source are provided.
 
-This project is not meant to be in production. Charts for the user interface are not implemented yet, so arrays of integers are displayed where charts will be placed in the future.  
-
-## Technologies
-#### Backend
-The Django web framework is used in the project to leverage quick development and the third party packages available.  Python requirements are kept in the requirements.txt file, and this file is generated using `pip freeze > requirements.txt`.
-
-Python 3.5 is recommended for this project.  It can be downloaded and installed at [python.org](python.org).
-
-#### Frontend
-The frontend source is written in ES2015 using [Angular](https://angularjs.org/). We are using [Angular Material](https://material.angularjs.org/latest/) for our styles.   
+Please be aware this project is not ready for production use.    
 
 ## Installation
 Docker is the preferred way to get an environment running. If you would like to not use Docker, please click [here](https://github.com/jakeharding/repo-health/blob/master/docs/Other%20Installation.md). Please note the Docker environment uses a development server and serves the backend application in a development state.  This is not safe for production use.
@@ -29,6 +20,20 @@ Step 3: Go to the root folder of `repo-health` and run `docker-compose up`. This
 
 Step 4: Once complete, a message will display saying that the server is listening to port 8000. You may now go to [localhost:8000](http://localhost:8000) to view this application.
 
+## Usage
+Once the app is installed and running, visit the localhost link above to enter a Github repository URL such as: https://github.com/cakephp/cakephp.
+
+You may also enter only the owner and repo name portion of the URL such as: cakephp/cakephp and acheive the same result.
+
+Please be aware the data set currently used is outdated and does not contain all the repositories on Github today.
+
+## Technologies
+#### Backend
+The [Django web framework](https://www.djangoproject.com/) is used in the project to leverage quick development and the third party packages available.
+
+#### Frontend
+The frontend source is written in ES2015 using [Angular](https://angularjs.org/). We are using [Angular Material](https://material.angularjs.org/latest/) for our styles. 
+
 ## Development
 To run UI tests:
 ```
@@ -40,15 +45,6 @@ To run Backend tests:
 python manage.py test
 ``` 
 
-## Production setup
-The app is not ready for production yet so this part is incomplete.
-
-Assumptions made about production:
-- Operating system: Ubuntu 12.04 or greater
-- Application will be running in it's own isolated environment, and a virtualenv is not needed.
-- Apache httpd server is used to serve app using mod_wsgi.
-- All static files are served from Apache using a redirect from url `/static/` to a static documents folder. This folder is created using `python manage.py collectstatic`.  This is not necessary in development.
-
 ## License and Copyright
 All source code is covered by the MIT license.  This license can be found [here](https://github.com/jakeharding/repo-health/blob/master/LICENSE.txt).
 
@@ -57,16 +53,4 @@ All other material, such as documentation, is covered by the Creative Commons -
 © 2017 Jake Harding and Benjamin Parish
 
 ## Contributing
-External contributions are not being accepted at this time. For existing contributors, please use the following header documentation at the top of each file:
-
-```
-fileName.ext - (C) Copyright - 2017
-This software is copyrighted to contributors listed in CONTRIBUTIONS.md.
-
-SPDX-License-Identifier: MIT
-
-Author(s) of this file:
-  Your name or github username
-
-Brief description of the file.
-```
+Please visit the [contributing documentation](https://github.com/jakeharding/repo-health/blob/master/CONTRIBUTING.md) for information on contributing to this project.

docs/Milestone3.md

@@ -0,0 +1,59 @@
+# Milestone 3    
+
+## System Description
+
+The system is a web based user interface and retrieves data about a GitHub repository using a URL specified by the user. The source code for the system is hosted on GitHub at: https://github.com/jakeharding/repo-health.
+
+The intent is to provide the user with usable information about a GitHub repository so the user can make an informed decision about the health and sustainability of the repository and the community supporting it.
+
+The system has many parts.  The backend provides a connection to the database, serialization of the data, and serving the data to the client in JSON format. The web client uses the JSON data to render the visualization of the data.  Both parts are included in the source code repository for convenience, but the system is built so the separation of the frontend and backend can be easily achieved. Docker simplifies the deployment of the project for demonstration purposes.
+
+The current state of the system is in a proof of concept and is not ready for a production environment.  The proof of concept supplies basic statistics about a repository and leaves out complex data manipulation.
+
+## Development Environment
+Our development operating system is a Linux/Unix (Mac) environment and our database management system is MySQL. 
+
+Our server is running on Python 3.5+ and is using the Django web framework and dev server.
+
+Our front end is using the node package manager (npm) to manage and keep our dependencies in sync.
+
+Docker is used to create an instance of the system as fast as possible and isolate the installation from other parts of the infrastructure running the application.
+
+## Posted Repository Issues
+- Jake - [GitHealth](https://github.com/Ashkeelun/GitHealth)
+- Benji - [Repos-Health-Study](https://github.com/Dreizan/Repos-Health-Study)
+
+## Walk-through of system
+Our system consists of an API and a UI that work together. After deploying our software, when you go to the website, you should be asked to enter a github url (name/repo). After entering a url,
+if it exists you will be presented with a new page. If it doesn't work, then you will see an error. After it was successful, you will see the details of the repository. You can then
+select issues or pull requests to see those statistics.
+
+## Data Flow Diagram
+Our Data Flow Diagram can be found [here](https://github.com/jakeharding/repo-health/blob/master/docs/Data%20Flow%20Diagram.pdf).
+
+## Database Schema
+We are using ghtorrent's schema. It can be found [here](http://ghtorrent.org/files/schema.pdf).
+
+## Copyright and License
+Licenses used for this project cover two areas: documentation and software.  The software is covered under the MIT license and the documentation is covered under CC BY.
+
+Each file has the following documentation: 
+
+```
+fileName.ext - (C) Copyright - 2017
+This software is copyrighted to contributors listed in CONTRIBUTIONS.md.
+
+SPDX-License-Identifier: MIT
+
+Author(s) of this file:
+  Your name or github username
+
+Brief description of the file.
+```
+
+## Contributions
+##### Jake:
+Jake is responsible for implementation of connecting to the database, the web server for the REST API, and all related documentation. 
+
+##### Benji:
+Benji is responsible for the frontend implementation. This includes UI/UX Design and the display of information from the server on the UI. All documentation for the frontend will be written by Benji.

docs/Other Installation.md

@@ -6,6 +6,14 @@ A Unix dev environment is recommended because the setup instructions provided ar
 ## Production Environment
 A Linux production environment is recommmended, and Ubuntu version 12 and greater is preferred.  A database will be needed and configuration for the database will need to be provided.  See below for database configuration.
 
+The app is not ready for production yet so this part is incomplete.
+
+Assumptions made about production:
+- Operating system: Ubuntu 12.04 or greater
+- Application will be running in it's own isolated environment, and a virtualenv is not needed.
+- Apache httpd server is used to serve app using mod_wsgi.
+- All static files are served from Apache using a redirect from url `/static/` to a static documents folder. This folder is created using `python manage.py collectstatic`.  This is not necessary in development.
+
 ## Database configuration
 Both production and development environments use MySql for a DBMS and require a database configuration specific to the individual environment.
 If using mysql 5.7 or greater, a warning may been seen due to strict mode being enable by default.  Turn off strict mode by adding a file named:
@@ -26,14 +34,16 @@ Open the MySql interpreter with root access using: `mysql -u root -p`.  If you h
 
 The user needs to have access to the database. Run `grant all on msr14.* to 'msr14'@'localhost;`.  After commands have been run successfully, run `quit;` to exit the interpreter.  We can now load the data into the database by running `mysql -u root -p msr14 < path_to_extracted_data_file`.  The `path_to_extracted_data_file` is the absolute path noted earlier, and `msr14` is the name of the database created.  Once this is successful, you can enter the information into the local_settings.py.
 
-Located in the `repo_health` directory of this repository is a `local_settings.py.example` file. Save a copy of this file as `local_settings.py` to the same directory.  Please do not remove the example file from the repo.  If you created the database and user as `msr14` then you will need insert the password for the user in the `PASSWORD` placeholder.  Otherwise enter the required information into the correct places and save the file.
+Located in the `repo_health` directory of this repository is a `local_settings.py.example` file. Save a copy of this file as `local_settings.py` to the same directory.  Please do not remove the example file from the repo.  If you created the database and user as `msr14` then you will need to insert the password for the user in the `PASSWORD` placeholder.  Otherwise enter the required information into the correct places and save the file.
 
 #### Production Database
 Production database is configured in a similar fashion, but the project is not ready for a production setup so this will be revisited.
 
 ## Backend Configuration
-Developers develop on many projects, and each project has it's own dependencies or deps.  
-For this reason, a virtual environment is created on the developer's machine in order to isolate Python dependencies between projects.  
+Python 3.5 is recommended for this project.  It can be downloaded and installed at [python.org](python.org).
+Python requirements are kept in the requirements.txt file, and this file is generated using `pip freeze > requirements.txt`.
+
+Developers develop on many projects, and each project has it's own dependencies or deps. For this reason, a virtual environment is created on the developer's machine in order to isolate Python dependencies between projects.  
 Virtualenv and virtualenvwrapper are used to create and maintain the environment and need to be installed in the base Python using the pip command line tool.  
 An explanation of how to install pip is [here](https://pip.pypa.io/en/stable/installing/), but if you can run `which pip` and see a result, you have pip installed.  
 To install virtualenv and virtualenvwrapper use:
@@ -57,13 +67,13 @@ To start using the virtualenv, run `workon <virtualenv name>`.
 From inside the virtualenv and in the project root folder, run `pip install -r requirements.txt` to install the deps from the file.
 Note for Linux users: `sudo apt-get install libmysqlclient-dev` may need to be ran from the terminal in order for MySQL to be used with the mysqlclient dependency. A mysql_config not found error will be present when running `pip install -r requirements.txt` to signify this.
 
-Once successful, the database is ready to be migrated. Since we are using an existing database and structure we will need to fake the initial migrations that normally created the tables and columns for each Django app using models that map the Github tables.  These are noted by packages beginning with `gh_`.  Run this command for every package in the `repo_health` folder: `python manage.py migrate <package_name> --fake-initial`.  After success run `python manage.py migrate` to run any other migrations.
+Once successful, the database is ready to be migrated. Run `python manage.py migrate` to run migrations.
 
 Run `python manage.py runserver` to start the built in dev server, and navigate a browser to [http://localhost:8000](http://localhost:8000) to view the index page.
 
 An admin is available at [http://localhost:8000/admin/](http://localhost:8000/admin/) when the server is running. In order to login to the admin a user will need to be created. Run `python manage.py createsuperuser` and follow the instructions.
 
-Run `python manage.py test --keepdb` to run the tests.  The `--keepdb` is important so Django doesn't try to destroy the test database.
+Run `python manage.py test` to run the tests.
 
 ## Frontend configuration
 From project root, `cd repo_health/index/static`.  

docs/README.md

@@ -2,10 +2,10 @@
 
 ## Purpose
 GitHub maintains a REST API so why do we need another? 
- - The reason to host and supply the data independentluy of GitHub enables us to structure the data in a fashion suitable for our purpose.
+ - The reason to host and supply the data independently of GitHub enables us to structure the data in a fashion suitable for our purpose.
 
 This presents a challenge in updating our database to stay current.  We recognize the need for data synchronization as an external entity of our system and outside the scope of our purpose. The documentation here provides structure and details for the repo_health REST API, which works with the msr14 database downloaded from GhTorrent [here](http://ghtorrent.org/msr14.html). This database is a subset of data and appears to be outdated.  This means many structure changes have likely occurred and will need to be accounted for when updating the database.
 
 The repo_health REST API accepts and returns JSON.
 
-Thank you to GhTorrent for providing the needed data and structure to get us started.
+Thank you to GhTorrent for providing the needed data and structure to get us started.