sawqxd / augur

Python library and web service for GitHub Health and Sustainability metrics.

Augur

branch	status
master
dev

About Augur

Augur is focused on prototyping open source software metrics.

Functionally, Augur is a prototyped implementation of the Linux Foundation's CHAOSS Project on open source software metrics. Technically, Augur is a Flask web application, Python library and REST server that presents metrics on open source software development project health and sustainability.

Development

---

Vagrant

The quickest way to get started working on Augur is by using Vagrant to spin up a virtual machine (VM) that comes with Augur already installed. We'll do all the work of setting up and installing dependencies, leaving you free to jump right into contributing something awesome.

Caveat: if you’re a super nerd who likes to have total control over your development environment, there’s a local installation link at the bottom of this page. For the rest of you, Vagrant is the way to go, especially if you've had trouble getting all the dependcies installed locally, are not comfortable installing them yourself, or are using an OS for which we don't currently support local installation. We currently only support local installation for macOS and most flavors of Linux.

Windows installation instructions using Vagrant can be found here.

Dependencies

• Vagrant
• Virtualbox
• GitHub Access Token (no write access required)

To get started, you'll need a VM provider- we currently only support Virtualbox. You'll also need to install Vagrant. To begin, clone the repository, enter the root directory, and run make vagrant.

# on your local machine
git clone https://github.com/chaoss/augur.git
cd augur
make vagrant

The first time you run this command, Vagrant will need to download the base box configuration. After that, it will provision the VM and then install Augur and its dependencies. Note: you'll probably see a fair bit of errors during this provisioning process as Augur is getting installed. Don't worry about them, most of them are harmless. Probably.

After this process has completed, the VM should be up and running. You'll then be automatically logged in to your newly provisioned VM. Log in as root with sudo su - and then navigate to /vagrant/augur. This folder is where you'll be working, as it's synced with your local version of Augur, meaning you won't have to worry about losing your changes after you shutdown the VM. You'll also be able to use your preferred editor. During the provisioning process, Augur will create a lightweight version of both the Facade and GHTorrent datasets, both of which we rely on for a lot of our metrics. You'll need to provide Augur with a GitHub Access Token (no write access required).

# inside the vagrant VM
sudo su -
cd /vagrant/augur

# due to vagrant weirdness, we have to manually install the python packages
sudo $AUGUR_PIP install --upgrade .

Augur will automatically create a config file called augur.config.json. Add your GitHub API key to this file under the section GitHub. At this point, you're ready to start developing! Run the backend with augur, or the frontend and backend together with make dev.

# to start both the backend and the frontend
make dev

If you're interested in adding a new plugin, data source, or metric, check out the backend development guide. If new visualizations are more your speed, you'll want the frontend development guide.

TL;DR

# on your local machine
git clone https://github.com/chaoss/augur.git
cd augur
make vagrant

# inside the vagrant VM
sudo su -
cd /vagrant/augur

# due to vagrant weirdness, we have to manually install the python packages
sudo $AUGUR_PIP install --upgrade .

# add your GitHub personal access token to augur.config.json

make dev
# full steam ahead!

Local Installation

To contribute to our code base routinely, we recommended that developers configure Augur on their local workstations. Start here to get a primer on the project, or jump straight into our local installation instructions for developers.

Guidelines

To contribute to Augur, please check out our development guide and notes on making contributions. Also, please note our code of conduct. We want Augur to be a welcoming development community that is open to everyone.

Roadmap

Our technical, outreach, and academic goals roadmap.

License and Copyright

Copyright © 2018 University of Nebraska at Omaha, University of Missouri and CHAOSS Project at the Linux Foundation

Augur is free software: you can redistribute it and/or modify it under the terms of the MIT License as published by the Open Source Initiative. See the file LICENSE for more details.

(This work has been funded through the Alfred P. Sloan Foundation)