Usability, Goals, and Future Directions

[wolfwood]

Before we start investing more in eg. documenting, adding tests, etc., I wanted to start a conversation about the goals of the project, and how we might most fruitfully pursue them.

Goals

0. ABOLISH ICE
1. GitHub drops ICE contract
2. Spread the protest
3. Easy to setup and run
4. Automatic refreshing
5. Platform agnostic
6. minimal dependencies (currently git and either wget or curl. I expect bash and date/grep/etc. to come with all *nix systems)

To me the number one action is to spread this protest as widely as possible. I heard about this from twitter, and I presume social media will be a good avenue for bringing more folks in going forward. But before hyping it further, I think we need participation to be as easy as possible. Ideally run one command to graffiti your commit graph, and also to register a cron / launchd / ???windows??? job to keep your graph refreshed every week.

It also should be usable regardless of your OS of choice. And to aid both ease of setup and the range of platforms supported, dependencies should be kept to a minimum. For example, while I would like to see the project use the GitHub API, we should do so without using the hub commandline tool or the jq json parser, even though these would be perfect additions in other circumstances.

These are my goals for the project and I am especially interested to hear if others feel differently.

Work flow

what (currently) needs to happen to get from 0 to graffiti

0. have commandline git and (optionally) either wget or curl installed (and have a github account)
1. get this repo
2. make a target repo on github (I recommend calling it abolish-ice)
3. get target repo onto local machine
4. make a second (remote) branch so we can switch default branches when rendering of the commit graph is screwy, ala #10
5. update dates.txt for current week, via ./dates.sh < dow.txt > dates.txt or ./raster.sh
6. run username=<user> <path_to_repo>/paint.sh in the target repo, with the user's name so we get the commit count right,
   • or <path_to_repo>/paint.sh if you don't have have curl/wget
   • or commitmax=<most_commits_in_one_day> <path_to_repo>/paint.sh if you don't have curl/wget and your colors are wrong cuz you have a pre-existing day with more than 50 commits
7. [optionally] switch default branch back and forth if things look wrong (checking the result by fetching the user's profile could also be automated)
8. [optionally] install cron / launchd / ??? job to refresh your graph next week

refreshing

9. switch default github branch back to the one without graffiti commits ( or maybe delete repo entirely and recreate? but this seems to cause more 'caching' issues)
10. hard reset graffiti branch from placeholder branch
11. update dates.txt for current week (5 reprised)
12. run paint.sh, with the users name (6 reprised)
13. paint.sh's git push will fail, so do a git push -f [maybe the git push doesn't really belong in paint.sh but in a parent script?]

Usability

The current collection of scripts is very flexible in how we choose to use them; in theory one could be graffiti'ing any pre-existing git repo. In practice, however, because the commits must lie on the default branch, a dedicated repo just for graffiti seems necessary. with this in mind we could automate 2, 3, 4 and 9, but we would need the user to generate a dev token (password access to the REST endpoints is deprecated and is ending in November, I believe).

To this end, I would like to investigate 'template' repositories a bit more, but using one for the graffiti'd repo might mean having slightly less hardcoding in the script proper, and it would be a good place to stick a README elaborating a bit on the DROP ICE campaign and highlighting the connections between Black Lives Matter and ABOLISH ICE, which are being made inside ICE detention, by immigration rights organizers, and by github employees.

Regardless of how it is achieved, my basic proposal is a single parent executable that automates the process and wholly manages a repository of its own. We should remove as many prerequisite steps and dependencies as possible. Whether we wish to optimize for non-git retrieval of the code base is open for debate.

Moving Forward

In part, this is a long winded way to say I'm not sure if bash is the best way forward. It has a lot of gotchas that things like shellcheck can help us with, but it's also not the ideal OS-agnostic platform, for running on windows, esp.

Moving to a scripting language (Python and Perl are my most familiar) or even a compiled language (I'm mostly thinking of Rust) would give us some real benefits.

• The recent date issue (#16) would have been prevented by using either Python or Rust date libraries.
• curl and wget could be removed as dependencies as there are libraries for HTTP
• there are pure Python and pure Rust implementations of git. while it seems reasonable to expect GitHub users to have git, many may have GUI git clients not commandline git
• Python also needs a linter, like Bash, but is moving toward type annotations and more static analysis tooling. the rust compiler is famously diligent. both language ecosystems have good testing support. I think is reasonable to say that the effort to reduce the odds of accidental bugs and regressions is lower with either than with Bash.
• github API use and json parsing would be easier without leaning on additional commands being installed like hub and jq.
• pip3 and cargo installed commands act like system commands and so don't need a relative path

Python2 is finallllly dead and Python3 is now in OS X Catalina by default, and I think there is a way to package Python scripts with an interpreter for Windows. Python also offers the chance to simply run pip3 install abolish-ice to get the latest code on *nix systems and for windows users with a python environment already.

If we go the Rust route, we can't expect most people to have cargo and rustc yet, but we could move to a 'download an executable' model for distribution on all platforms.

My Ask

It boils down to 2 things:

1. looking to get buy-in for the vision of a more highly automated workflow
2. feedback, esp. from @rossabaker, about whether a switch of languages is on the table for discussion, or not. Specifically for the above automated process. also, it might be that for supporting multiple platforms a diversity of solutions will make the most sense.

Regardless of outcome, I've had these things in the back of my mind for a while, and I thought now was a good time to get some clarity around this before doing additional work in Bash.

[wolfwood]

@lindsaylevine there is an abridged user guide hidden in this wall of text :laughing:

[lindsaylevine]

looks great!! @wolfwood

[rossabaker]

Wow, I never expected my grumpy Saturday morning shell script to turn into anything this ambitious. I agree that this repo is most effective with less friction to render and maintain the graphic. (Mine, sadly, is fading and scrolling to the left.)

I would be on board with a language switch. I'm an old Perl hacker and have done a bit of Python, bu I don't associate either of those with being easy to distribute, particularly once they depend on libraries. Rust or Go, with cross-compiled static binaries, are two obvious choices. I've done a little Go, but don't enjoy it. I've done no Rust, but am interested. I'm most comfortable in Scala and Haskell, but static binaries require some effort in both, and don't seem like the right fit here.

If you know Rust, I think it's a reasonable technical choice and could be my kick in the ass to learn.

[wolfwood]

It would be an exaggeration to say I know Rust, but I've dabbled and I'm committed to learning it in the near term, regardless.

My Haskell is rusty, but I'm sure we could write some pretty Functional Rust :smile:

[BenBE]

What about automating 2,3,4 & 9 by some script in our repo that just wants to be given a path, username and repo-name (on GH) and auto-creates the repo locally (IIRC you should be able to create a repo, by just pushing to it under your username). That said you can automate the refresh by checking for the .git directory, git init if it doesn't exist, and do some git checkout --detach magic to kill the current branch for recreation (IIRC: git checkout --detach; git branch -D main). The remotes follow baed directly on the username and reponame given as arguments, thus recreating the remotes and force-pushing should be no problem. Everything said is doable with only few lines of shellscripting …

I thus don't see any pressing reasons to switch languages.

[wolfwood]

Unfortunately, you can no longer create a repo by pushing. You have to use the API such as curl -u 'USER' https://api.github.com/user/repos -d '{"name":"REPO"}'

you also cannot remotely delete the default branch of a repository using git push. we can partially work around this by force pushing, but it seems to increase the chances of #10, so switching the default away before the push, and then back seems needed.

So we are going to depend more heavily on the API,eventually want to parse responses and errors, etc. Obviously anything is possible in bash (I was getting ready to start writing what you propose), but its going to get increasing fragile in avoidable ways.

more fundamentally though, @BenBE what is the story for bash under Windows? I'm not a Windows user myself, but I think that if the goal is to spread this protest as widely as possible, we cannot ignore them, and requiring them to setup cygwin or have WIndows 10 Pro and enable WSL (which I never got working at my old job) seems almost as bad as saying its unsupported, esp. if none of us test there regularly.

Using, e.g. Rust, gets us platform agnostic path handling, ergonomic HTTP libraries, much greater faith that if something works on Linux it works everywhere, and 0 dependencies.

[BenBE]

Usually when running Git on Windows you usually have either Git for Windows, which is a glorified MSysGit and contains a reasonable POSIX environment (GNU compatible IIRC) or running Cygwin with Git installed (headache, but also provides all required tools) or you're using WSL, in which case you've a whole Ubuntu at your disposal. Only issue is if your IDE integrates Git and you don't run an extra client like Git for Windows.

At least for Cygwin and MSysGit I can tell from another project of mine that the tooling there is kinda reasonably recent. And yes, that's a full command line extension written in pure bash.

If there's really a need to have such a campaigning tool on all platforms I'd suggest to go with Python: This keeps the barrier for entry kinda low, comes with easy options to build binaries and doesn't diverge too much from the small tools idea. I don't think though the pure bash tooling should be dropped entirely. Campagnes work best if there's a bit of work required to spread the message as it strengthens the trust that someone presenting this message really thinks that way.

That said: The fun part for me in this project was demonstrating what is possible with a bit of bash scripting and reading the docs.

I don't consider "auto-spraying" the message everywhere a sensible means, as every developer (and that's a large part of GitHub's community) should be able to use his tools; with maybe some minor tweaks hinted as necessary. Having said this: With basically the step-by-step guide in the first message of this issue everyone serious enough about the matter should be able to get this working OR come up with the right questions to ask for help. Make things easy, but not too easy!