Discovering GitHub APIs while learning Clojure

As a developer, it's important to keep on learning/discovering stuff. Quoting The Pragmatic Programmer :

Invest Regularly in Your Knowledge Portfolio

My last project "for learning" was to create a command-line tool, named hubstats, that outputs a summary for pull requests GitHub. This tool aims at giving some metrics for me and my team.

The real purposes were to practice Clojure (which I knew little) but also to discover REST and GraphQL GitHub APIs.

Moreover, I was lucky to interact with a colleague of mine who is an advanced Clojure developer. That was really cool, thanks Jérôme aka @jprudent!

What is hubstats?

hubstats is a simple command line tool that outputs, for a given GitHub repository, the number of opened/commented/merged pull requests by author for a given period (last week, since a given date, etc.).

Here is an output example:

lein run --organization softwarevidal --repository arthur --token $token
pull requests for softwarevidal/arthur ->
    since 1 week(s):
        9 opened / 56 commented / 5 closed
        opened per author: {"cmahalin" 5, "jcgay" 2, "AElMehdiVidal" 2}
        commented per author: {"vidal-rm" 30, "jcgay" 17, "cmahalin" 9}
        closed per author: {"cmahalin" 2, "AElMehdiVidal" 2, "jprudent" 1}

How does it work?

I have chosen Clojure, a language that is different from the language that I use every day (Java).

The following characteristics appealed to me:

• dynamic and interactive development: code is short and simple, which seems cool for an internal tool; what's more, the REPL is a base tool that greatly fit to a discovery mindset.
• functional programming: functions are first-class citizen, immutability and function recursion are basics
• Lisp: Clojure is a Lisp, so writing code is a bit different from C-like languages ; Code is data and can be edited via paredit (emacs-like mode for editing code while keeping parentheses balanced).
• simplicity: Clojure encourages too use small libraries instead of huge frameworks.

See Clojure Rationale.

My dev setup:

• IntelliJ IDEA with Cursive plugin
• Cursive paredit mode
• Leiningen as build tool
• Travis CI for continuous integration

So what?

What I liked:

• a "parenthesis" (haha!) with my daily Java routines/habits
• paredit is confusing at first, then pleasant to use
• REPL rocks for
  • shaping code (acts as a draft for new code)
  • troubleshooting bugs (example: incorrect GitHub pagination traversing that led to out-of-memory crash)
• unit tests are easy to write (example: with-redefs macro can be used to mock functions: https://clojuredocs.org/clojure.core/with-redefs)

What I did not like:

• WTFs when runtime bugs occurred (obscure stack traces)
• integrated documentation lacks examples. I often had to browse Clojure Docs to understand Clojure base functions via useful examples.

What's next?

Some ideas for some evolutions (or an other project, maybe?):

• use GitHub GraphQL
• make a web app for hubstats (via ClojureScript?)
• build another CLI tool
• learn another language (for example: Go or Rust)

That's all folk! 😉