Work-flow is very personal, it depends on how we think and what tools we are comfortable with. I strongly believe that reducing cognitive effort is a worthwhile exercise. It leaves more head-space for actual work and return works like compound interest.
Anyways, that’s how I contribute to Github currently. Maybe it will be of interests to others.
It all starts with a project
First I need to figure out how it’s structured and how it works.
Github has taken great efforts to make code spelunking more user-friendly but no web solution beats the speed of my own editor. I’m going to take a peek of the project’s README.md but quickly enough I want to have a version of the code sitting on my disk.
For that I have adopted a standardized file-system layout. All projects are
~/code/github.com/<user>/<project>. Combined with this little
shell extension (h) which automatically
clone into the standardized place and
cd there I don’t have to think
whenever the project has been checked-out or not.
|In cases where projects are renamed this system requires some hand-fixing.|
$ h nixos/nixpkgs Cloning into '/Users/zimbatm/code/github.com/nixos/nixpkgs'... remote: Counting objects: 14292, done. remote: Compressing objects: 100% (10096/10096), done. remote: Total 14292 (delta 467), reused 10580 (delta 349), pack-reused 0 Receiving objects: 100% (14292/14292), 8.74 MiB | 4.27 MiB/s, done. Resolving deltas: 100% (467/467), done. Checking connectivity... done. $ pwd /Users/zimbatm/code/github.com/nixos/nixpkgs
INFO: When a couple hundred of projects are created in this file structure it
can become a bit unwieldy to remember what user was owning which project.
<project> will find the longest match in that structure.
autojump is also great for jumping around using fuzzy searches of previously-visited directories.
The code is not on some remote server anymore. It makes it easy to start
poking around and maybe create a
git branch ? Maybe create a commit or two ?
$ git checkout -b shake Switched to a new branch 'shake'
One important aspect of contributing is to make sure the code is valid. It
must therefore be easy to be able to run the code and hopefully some
associated tests. Because I’m living in the shell so much, I want to be able
to load different versions of ruby, python, haskell, perl, … Each language
has their own version-switcher(s). Instead of installing all of them I’ve
created a sort of language-agnostic environment loader for the shell called
direnv. When moving around with
h direnv takes
care of loading and unloading the appropriate project dependencies.
Here I just want to set the
NIX_PATH so that it uses the current project as
the source of packages instead of one of the system channels.
$ direnv edit . (1) export NIX_PATH="nixpkgs=$PWD" # :wq (2) direnv: loading ~/.direnvrc direnv: loading .envrc direnv: export ~NIX_PATH
write file and exit the editor
Okay so now there is a branch with some nice code. The fastest way to push that upstream is by using the hub command-line tool.
$ hub fork (1) Updating zimbatm remote: Counting objects: 21, done. remote: Compressing objects: 100% (19/19), done. remote: Total 21 (delta 4), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (21/21), done. From https://github.com/nixos/nixpkgs * [new branch] 0.5-stable -> zimbatm/0.5-stable <snip> * [new branch] xpra14 -> zimbatm/xpra14 new remote: zimbatm $ git push -u zimbatm shake (2) Counting objects: 10, done. Delta compression using up to 4 threads. Compressing objects: 100% (9/9), done. Writing objects: 100% (10/10), 1.18 KiB | 0 bytes/s, done. Total 10 (delta 7), reused 0 (delta 0) To firstname.lastname@example.org:zimbatm/nixpkgs.git * [new branch] shake -> shake Branch shake set up to track remote branch shake from zimbatm by rebasing. $ hub pull-request (3) shake: new package Hi, shake is a build tool written in Haskell. Since the build tool is not limited to haskell projects I took the liberty of putting it in the top-level. Is that alright ? shake's default.nix is generated with cabal2nix cabal://shake > default.nix but was missing gcc as a test dependency. Is there a better way to add gcc as a dependency without having to add it back on the next shake update ? #:wq (4) https://github.com/NixOS/nixpkgs/pull/9283
creates a fork to zimbatm/nixpkgs and sets the "zimbatm" remote
push the branch to zimbatm/nixpkgs
opens the editor
write file and exit the editor
Done (waiting on review)
This work-flow is very shell-centric and I love it.