jubalh / gontributions

open source contributions lister

gontributions

open source contributions lister

This program lists your open source contributions. They get printed on your terminal when running the program. Additionally an HTML page gets created. There are some templates in the templates directory. Feel free to add your own and create a pull request to this repository.

Sometimes upstream repositories disappear. And with it your contributions. Initially I wrote this program as a way to back up all the repositories I contributed to and get a list of my contributions. Either because I was proud of them, or because I might wanted to look at them again. In any case, I just like backups. From there the program grew, to create a small overview in HTML format so you could show the projects you contribute to to others.

Please read MEANING.md to learn more about what is tracked and how to interpret the information.

Requirements

The following binaries need to be (optionally) installed:

• bzr for Bazaar support
• git for git support
• hg for Mercurial support
• osc for Open Build Service support

Installation

go install github.com/jubalh/gontributions@latest

Optionally create the man page:

pandoc --standalone --to man doc/gontributions.1.md -o gontributions.1

Configuration

You need to create a json file containing your open source contributions. The format is pretty easy. It is best to create an example configuration file and adapt it.

Create an example json configuration and adapt the example to your needs:

gontributions exconf > example_conf.json
vi example_conf.json

Get an overview of your open source contributions:

gontributions --config example_conf.json
xdg-open output.html

Choose another template for your overview

gontributions --config gontrib.json --template detailed --output another.html
xdg-open another.html

If you don't specify a configuration file it will automatically look for gontrib.json.

There are three built-in templates:

• default
• detailed
• fancy

If no template is defined it will use the built-in default template.

The user can create his own templates and specify them via --template. Like --template mine.html. If the specified template contains no dot, gontributions will look in its built-in templates. If it contains dots it is treated as a path for a user created template.

Usage

Please read the USAGE.md file for more hints on how to use gontributions.

Features

Search for commits in:

• Git

• Subversion

• Mercurial

• Bazaar

• Open Build Service

• support to count Wiki edits

• count Debian Testing changelog entries

Display:

• project name
• description
• project URL
• number of commits/contributions

Contribute

There are some features that would be nice to have, but I don't need them myself. I created issues about them. Feel free to work on them or implement your own ideas.

You might want to read HACKING.md.

FAQ

Does it have to be Open Source?

You could also add private repositories and just publish the finished report. No one will learn about the location of the repos, your precious commits or your username. Still you would have a nice overview of what you did.

Furthermore: if someone deletes a repository you contributed to, you still have your local copy if you use gontributions which will count into your contributions report. If we would just query some remote server you don't have any control over it. When it's deleted it's just gone. And your work lost.

But there is 'GitHub Contributions'!

Right. There is. But:

• It only displays contributions in a certain timeframe, you have no control over it.
• It works only for GitHub. What about your contributions hosted at GitLab, BitBucket or on sourceforge?
• What about your non-git Contributions? Like wiki edits, subversion commits etc.

But there is Ohloh/Open Hub!

Right. There is. But:

• The service hangs often so you need to ping admins to restart the scanning tool.
• You rely on a service you don't have much control over
• See about deleted repos above.

What else is cool about it?

Quite a few people use their personal website as their resume.
With this tool you can add an overview of the work you did and you can adjust the look and feel to the rest of your website. If you rely on Open Hub it will always look like Open Hub, if you create your own template for gontributions your report has totally your touch.

Can I see such a report please?

Glad you ask. Of course you can!
Take a look at mine.

gontributions's Issues

pretty templates

Add at least one really pretty template.
I would like to create a new repository where all users can upload their templates maybe following a standard structure:

githubusername-templatename/default.html
jubalb-green/index.html
jubalh-green/img/background.png
jubalh-green/css/main.css

For example.

I am not very interested in this myself as I prefer the basic templates but would be nice to have a default pretty one for others.

add subversion support

Dont have any public svn repo I contributed to I think. So this has no prio for me. Feel free to add it!

add bazaar support

much can be taken from 'git.go' I guess.

How to use Wikipedia as source of commits?

osc cat

dont checkout whole version including tarball, just use osc cat to check the standard changelog.

save wiki edits in file

or whole struct

Have more details

I thought about instead of having a simple:

type Contribution struct {
    Project Project
    Count   int
}

See https://github.com/jubalh/gontributions/blob/master/gontrib/contributions.go#L34

To use something like:

type Commit struct {
    hash    string
    time    string
    email   string
    subject string
}

type Contribution struct {
    name        string
    description string
    gitrepos    []string
    commits     []Commit
}

Or similar. This way the user could have more detailed stuff in his templates if he wishes.
For example he could create an overview like this:

My Contributions

Funtoo Linux:
  34f52x Update vifm
  3d2s5  Fix LXQt profile

Next project
  hash  commit message
...

He also could sort his contributions by time/date and do other fancy stuff.

It might be worth considering this. As for me, I only need the basic behaviour right now. Which is why I only implemented the basic behaviour. If others like to use the project nd would like to change, go for it.

The only draw back is: if the user only wants a simple overview he has to add all the contributions together to get the sum. I think.

Don't make assumptions on template paths

Right now when I provide a template via the --template flag the binary assumes the template are located inside templates directory.

$ gontributions --template fancy-template.html --config example.json --output index.html
Asset templates/fancy-template.html not found

I expect the --template flag to allow for full/relative paths

add commit revisions to config

We should be able to mention certain commit revisions that we contributed too in case an upstream project didnt apply the patches correctly thus not saving authorship.

Example

I am unable to use templates not bundled with the binary

When providing the a template called default.html to the --template flag the output is generated with no errors.

$ gontributions --template default.html --config example.json --output index.html
* Working on https://github.com/jubalh/nudoku
Already up-to-date.
==> [email protected]: 30 commits
==> [email protected]: 53 commits
* Working on https://github.com/boothj5/profanity
Already up-to-date.
==> [email protected]: 9 commits
* Working on https://github.com/funtoo/ego
Already up-to-date.
==> [email protected]: 5 commits
* Working on https://github.com/funtoo/metro
Already up-to-date.
==> [email protected]: 1 commits
* Working on MediaWiki http://funtoo.org as jubalh
==> 93 edits

Report saved in: index.html

Whereas when using a template called fancy.html the binary can't find any template.

$ gontributions --template fancy.html --config example.json --output index.html
Asset templates/fancy.html not found

Moving the fancy.html template to a directory called templates does not help.

write tests for every module

Output of golint

golint has some complains:

$ golint ./...
gontrib/contributions.go:11:6: exported type Project should have comment or be unexported
gontrib/contributions.go:14:2: struct field Url should be URL
gontrib/contributions.go:18:6: exported type Configuration should have comment or be unexported
gontrib/contributions.go:23:6: exported type Contribution should have comment or be unexported
vcs/git.go:11:6: exported type RepoData should have comment or be unexpected

Those should be addressed.

Check if binaries exist before using

We should check if obs, git etc exist before attempting to use them or at lesat print out a message.

add mercurial support

Dont have any public hg repo I contributed to I think. So this has no prio for me. Feel free to add it!
Much can be taken from git.go I guess.

List contributions to your personal open-source projects

Could there be an option to list personal open-source projects ? The infrastructure you have here would make it pretty easy to do, but I want to know whether you think this is within the scope of this project. Namely it would be nice to have a contributions page like:

Contributions to other projects:

openSUSE 
openSUSE Linux distribution 
322 contributions 

...contributions to other projects..

My Projects (* = founded by me):

gontributions *
open source contributions lister
68 contributions 

...my own projects...

I think this would be easy to do. You could just clone repos as before, but you would count the number of commits by each person and determine

1. If it is founded by you by looking at whether you made the first commit, and
2. whether it is your project by seeing if the majority of contributions came from you.

Then you could list it under My Projects if the majority was contributed by you and add a * if it is founded by you.

Have an error log

In very long outputs it could be that there happens an error with checking out a repo but the list is so long that you miss it.
In this case we want a note when the program finishes and have a special error file.

Distinguish/Mark own projects vs contributed projects

We would need a banner or star or just some text note to distinguish whether we started/took over maintainership for a project or just did a simple contribution.