jameslamb / oss-report Goto Github PK

View Code? Open in Web Editor NEW

3.0 3.0 2.0 57 KB

Make a report on one or more users' open source contributions

Python 26.62% JavaScript 54.16% HTML 7.91% Vue 6.44% CSS 2.80% Shell 1.02% TSQL 1.06%

vuejs api open-source flask

oss-report's Introduction

oss_report

This little app allows you to visualize the activity of a GitHub user. It's that simple.

From source

Grab the repo

git clone https://github.com/jameslamb/oss_report.git
cd oss_report

Kick up the app

# Build
docker build -t oss_report:$(cat VERSION) -f Dockerfile-app .

# Run
docker run -p 5090:5090 -d oss_report:$(cat VERSION)

From dockerhub

Pull and run the container from dockerhub.

docker run -p 5090:5090 -d jameslamb/oss_report:0.0.1

Use the service

Navigate to localhost:5090 in your browser to view the app!

You can hit the /api/events endpoint to get JSON data with all the relevant activity a user took in the last 90 days.

curl -XGET http://localhost:5090/api/events?user=jameslamb

Pushing to Container Registry

If, for whatever reason, you want to build and push a version of this to your own space in a container registry like Dockerhub, you can use publish.sh.

./publish.sh your_repository_name

Note that this will tag the container with the version number stored in VERSION.

Authentication with the Github API

Note that this service hits the Github API. This API's rate limit policy states that unauthenticated requests are limited (by IP address) to 60 requests per hour. Authenticated requests are limited to 5000 an hour.

If you want to run this app authenticated as your Github user, set the GITHUB_PAT environment variable to an OAUTH2 token generated from https://github.com/settings/tokens.

I recommend setting up a .env file with something like this:

GITHUB_PAT="my_github_key"

And then reading it into the container at run time.

docker run -p 5090:5090 --env-file creds.env -d jameslamb/oss_report:0.0.1

Case Study: Analyzing an Organizational Open Source Program

The UI and supporting server code in this project mainly support an interactive one user at a time workflow. However, they can be used to support another workflow: tracking the open source participation of a group of users, such as all members of a meetup group or participants in a company's open source initiatives.

Running this analysis for the first time

Kick up an instance of the app running on localhost:

docker run -p 5090:5090 -d oss_report:$(cat VERSION)

Generate a SQLite database file in the analyze/ folder.

cat analyze/schema.sql | sqlite3 thing.db

Populate a CSV with your users.

user_name: Github user name (e.g. jameslamb)
full_name: full first and last name (James Lamb)

For example:

echo "user_name,full_name" > thing.csv
echo "jameslamb,James Lamb" >> thing.csv
echo "bburns632,Brian Burns" >> thing.csv
echo "jayqi,Jay Qi" >> thing.csv

Run the update script that will seed the database with users and pull events for each of them

python analyze/update_db.py \
    --csv-file $(pwd)/thing.csv \
    --db-file $(pwd)/thing.db \
    --api-url http://localhost:5090

You can now query thing.db to build any reports you want!

For example, you can run this to get an overview of activity by user.

sqlite3 \
    -column \
    -header \
    thing.db \
    'SELECT user_name, COUNT(*) AS total_contributions, COUNT(DISTINCT(repo_name)) AS num_unique_repos FROM events GROUP BY user_name;'

Updating an existing DB

The Github API only allows you to get the last 90 days of activity, so you may want to run this process regularly to build up a longer history over time.

If you already have the CSV and DB files generated, just kick up the service and run the update script!

docker run -p 5090:5090 -d oss_report:$(cat VERSION)
cd analyze/
python update_db.py

References

oss-report's People

Contributors

Stargazers

Watchers

Forkers

crazyglue austin3dickey

oss-report's Issues

Contributors vs. Maintainers

Right now, the types of events this tracks are all grouped under one header and tend to be contributor specific (like "PRs submitted").

Should add maintainer events types and break them into a separate section. So, for example, "Issue closed", "Pull request closed".

Group events by repo

Would be great to have collapsible sections for each repo with their associated events

Right now, you get the last N events which doesnt give a good picture of their overall activity

Add message if the search turns up nothing

Right now, if the response from the events endpoint is {"activities":[],"events":[],"total":0,"user":"this_user"}, nothing happens in the UI. I think it would make sense to display a message instead.

Feature Request: Option to pull all events by org

What's your appetite for this?

As an additional function and/or optional command line function, a user of this package can simply specify the name of a github organization and all users and public activity from those users will be returned.

Here is the github api call: githubAPI members list. This could be either:

an alternative to specifying a csv of user names OR
a way to generate a csv (then rest of process remains the same)

Additionally, an option to pull outside contributors via the api could follow the same approach.