github-docs VS cli

In college, an English professor would ask me and other students the following question when reviewing our essays, “Where are the examples?” Developers ask the same question when reading your documentation. To write good technical writing documents, include examples that developers can see themselves implementing in their work. How can this be done? By adding examples from your product’s codebase! 🙂 Let’s look at this code snippet from my contribution to GitHub’s documentation:

Need an example? Check the GitHub docs contributing guide.

git clone https://github.com/github/docs.git 123.57s user 37.02s system 74% cpu 3:35.73 total

git clone --depth 1 https://github.com/github/docs.git 3.37s user 1.83s system 35% cpu 14.521 total

Not a scientific test at all, but the second one was literally 35x faster, wall clock time.

Docs

The strange thing is that I only have this problem with github, all other websites work just fine. And even docs.github.com works fine...

99.9 at best for enterprise cloud: https://github.com/github/docs/blob/main/content/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement.md

A project repository typically has a license file at the top-level indicating which license the code falls under. See here for an example license file.

This package is widely used for powerful CLI builds, it is used for example for Kubernetes CLI and GitHub CLI, in addition to offering some cool features such as automatic completion of shell, automatic recognition of flags (the tags) , and you can use -h or -help for example, among other facilities.

This Docker image is designed to support implementing Github Actions with Python. As of version 4.0.0., it starts with the official python docker image as the base which is a Debian OS. It specifically uses python:3-slim to keep the image size down for faster loading of Github Actions that use pyaction. On top of the base, we've installed curl gpg, git, and the GitHub CLI. We added curl and gpg because they are needed to install the GitHub CLI, and they may come in handy anyway (especially curl) when implementing a GitHub Action.

You might be interested in GitHub's cli tool, which is open source, if you want to access GitHub without running their proprietary JS code.

https://cli.github.com/

👉 Note: This script uses the GitHub CLI. So make sure you've installed that if you haven't already. Instructions here.

View on GitHub

(Context: I'm pretty thick into Nix, and have been for about four years. Most of this post is focussed on the NixOS desktop experience, so DevOps nerds, ymmv.)

Unpopular opinion: Nix is not that hard.

What's "hard" from a nix-promotion strategy is motivating people to understand why they would want the benefits it offers. Mostly because Nix, especially with home-manager, dramatically worsens UX for several day-to-day tasks, simply by violating the Law of Least Surprise every couple of hours in normal use.

I want a fully idempotent, version-locked, rewindable user environment, with a version-controlled central config, because I have half a dozen devices that, for reasons, I need to keep perfectly interchangeable with one another. Most users do not want this, for the simple fact that mutating their configs and differentiating them locally on specific machines is not a bug, but a feature.

Even more than that, it's an expectation that most software developers share as well.

Case in point: I filed a bug against the GitHub CLI last week. If any org has the scope and motivation to build software that's compatible with NixOS, an OS most of whose users are developers, it should be GitHub, which is, at least notionally, all about developers, developers, developers. A change in GH required a config format migration, which was sensibly done by opening the config .yml and rewriting it.

Of course, this breaks NixOS not just in practice but in principle. NixOS/home-manager makes config files read-only. Surprise! https://github.com/cli/cli/issues/8462

The response from GitHub was basically, "yeah, we knew this was going to happen, we mentioned it to the packagers at NixOS, but we did it anyway, because it was still the best way to proceed for us." (And they weren't wrong.)

Now, once a month is an annoyance, but I run into these problems daily. I can't imagine any sane person -- which I am not -- would persist with using it.

Why do I keep using NixOS, then? Because I am terribly and disproprotionately annoyed by small changes in my user experience, which I find disruptive to my workflow and hence threaten my success. For me, forbidding apps from mutating the config files I established for them is a selling point. Being able to version-control an idempotent declarative config for all of them at once is heaven.

Unless you're like me, you'll hate NixOS. But some were meant for Nix.

Because

To use a proper dynamic auth for ghcr.io you can create a "credential helper" and then it is supported by flux, see here: https://fluxcd.io/flux/cheatsheets/oci-artifacts/#authentication Unfortunately the "official" credential helper for ghcr.io doesn't exist. I use this simple script as a helper: https://gist.github.com/pkit/a98411d21ecc9293066f4579088187d1 Which requires gh cli to be installed.

This Docker image is designed to support implementing Github Actions with Python. As of version 4.0.0., it starts with the official python docker image as the base which is a Debian OS. It specifically uses python:3-slim to keep the image size down for faster loading of Github Actions that use pyaction. On top of the base, we've installed curl gpg, git, and the GitHub CLI. We added curl and gpg because they are needed to install the GitHub CLI, and they may come in handy anyway (especially curl) when implementing a GitHub Action.

Two CLI tools I install right away are the GitHub CLI (via brew) and the Netlify CLI (via npm).

From the second article, a minor point but possibly helpful to other here, he contrasts doing everything in the terminal with stacked commits vs going to the Github UI. If people aren't aware, Github offers a cli tool[1]. I've been using it for a few months now and am finding it does make me more productive -- it's nice to be able to open up a PR directly from my terminal. I do still use the GH UI for a lot of things, but I'll often at least start in the terminal, and it also makes the transition from terminal to browser easy as many commands support the `--web` flag open up the right page for you (eg `gh repo view --web`).

[1] https://cli.github.com/