hackday: gh repo garden

[vilmibm]

For this hackday I wanted to create something interactive that was unique to a given repository. As
a big fan of games like Angband I decided to make a repository a top down thing that can be explored. I wanted to convey a sense of people coming together to make something that they couldn't do on their own, so I chose to render a repo's commits as a garden of colorful flowers. The color of each flower is the first 6 characters of a commit's SHA interpreted as a hex code; the character of each flower is the first letter of a commiter's GitHub handle.

In addition to the commit flowers, there's:

• a border of trees
• a randomly placed stream
• a sign saying the name of the repo

Considerations

• The flowers are placed randomly but the random seed is based on the repo name; that means that two people looking at the garden for the same repo will see the same layout but each repo's layout is different.
• This takes advantage of modern terminals' support for 24 bit color. I added utils.RGB(r,g,b,s)
  which can output text of any RGB color. I used this to more accurately convert SHAs to color and
  also to make a gradient fill for the stream.
• Like my last hack day project, I did not introduce any new third party libraries
• This uses the GitHub API to get commits. I started out using git log which is nice and fast
  but this meant you couldn't generate a garden for an arbitrary repository; it also meant that
  getting the GitHub handle for a committer was challenging. Using the API is a little slow but I'm
  happier with the results.

Future directions

I'd like to render a much larger space that can be panned around while the user moves. Given a
larger space, I'd render more about a given repository: projects as monuments, closed issues as
graves, contributors as wandering NPCs, etc.

I'd also like to animate it when the user is standing still. Right now it only redraws when the user
moves. I want the stream to twinkle and the grass to move in the wind.

[mislav]

I would love to see this merged! I'm sorry for the late review.

Since this is likely something that we would ship once and avoid refactoring too much, I think it would be beneficial if it was in its own package. Would you be open to moving the implementation to under pkg/cmd/repo/garden/ and for it to use a raw HTTP client directly (like api command does) rather than adding an extra method to the api package? It might be a nice pairing project for us; let me know!

[leereilly]

SHA-mazing! 😍

If you're looking for an excuse to demo this, and/or watch a whole bunch of talks from fellow Roguelike developers and players, the Roguelike Celebration (usually hosted at GitHub HQ) might still be looking for presenters. I know the organizers well if you'd like an intro!

Check out the videos from yesteryear on YouTube.

[vilmibm]

@leereilly oh awesome! Thanks for suggesting that! I've watched videos from that event in the past.

This is a humble little thing and I don't think I could spin it into a talk of any significant length. It might be suitable for a lightning talk; alternatively I can submit next time around once it's more fleshed out.

[vilmibm]

@mislav sorry, I totally missed your review 🤦 I've removed the additional method from api.client and isolated this command entirely in its own package in the new command format.

[vilmibm]

ok, this works fine on macos now 👍

[mislav]

Couple of minor points before this ships

[mislav]

If q is Left now, how do we exit the garden?

[leereilly]

The only way I can exit (on macOS at least) seems to be CTRL C.
That seems acceptable / consistent with gh credits? Q doesn't work for me there either FWIW.

cli/pkg/cmd/repo/credits/credits.go

Line 190 in 5e11fe8

lines = append(lines, "( <3 press ctrl-c to quit <3 )")

[vilmibm]

just switching to ctrl+c for quitting seems ok to me

[mislav]

Sure! I was simply asking about q since it was documented as an exit technique for the garden.

Ctrl-C works, but does not print the nice exit message:

You turn and walk away from the wildflower garden…

[vilmibm]

After testing this for a while I was unhappy about losing q; I ended up just making the arrow keys work, finally, so that is an option for anyone who doesn't want WADS or vi keys.

[vilmibm]

• flickering is fixed; only redrawing what needs to be redrawn, now
• added support for arrow keys. since this is in, i took out azerty support so we could have "q" back for quitting
• GHES supported

[mislav]

Fantastic! Works like a charm.

One final optimization might be to cap max commits fetched. With a fairly medium terminal size of 150×50, 7,500 commits would need to be fetched, resulting in 75 HTTP requests each taking 500–600ms. When I maximize my terminal window, it wants to fetch 26,394 commits. For projects that actually have that many commits, this would result in long loading times.

I understand that this isn't a mission-critical command that should be fine-tuned for performance, but I'm thinking that at least there should be some guard mechanism in place to prevent the command from seeming like it's stuck or exhausting the viewer's API rate limit.

[mislav]

Protip: you can now use opts.IO.StartProgressIndicator() + opts.IO.StopProgressIndicator() to get the spinner rendering 👌

[vilmibm]

I understand that this isn't a mission-critical command that should be fine-tuned for performance, but I'm thinking that at least there should be some guard mechanism in place to prevent the command from seeming like it's stuck or exhausting the viewer's API rate limit.

good point; I was definitely over requesting during the hackathon and never circled back and capped it. For now I just halved the product of terminal height/width to make it a little better since we were never going to make use of all the commits anyway.