Quickly and Easily Publish Your Scala Code for Use in Other Projects


## Intro

Say what you will about JavaScript, but [npm](https://www.npmjs.com/) has made it incredibly easy for anyone to publish code. In just a few clicks, you can share a library to make others' lives easier, or publish a little snippet like [`left-pad`](https://qz.com/646467/how-one-programmer-broke-the-internet-by-deleting-a-tiny-piece-of-code/) to cause endless headaches.

Java has long had the [Maven repository](https://mvnrepository.com/) (and accompanying build tool of the same name), which serves a similar purpose: sharing packaged code.

But it can be intimidating for a newbie to publish to Maven -- that's where Sonatype comes in.

Sonatype, Inc.'s [Central Repository](https://central.sonatype.org/) (a complement to Apache's Maven repository) makes it super easy to share code. With just a few lines and a few manual steps, you can publish your package to Maven, and others can easily import it and use it.

sbt's [Using Sonatype](https://www.scala-sbt.org/release/docs/Using-Sonatype.html) guide and Sonatype's [Deployment Guide](https://central.sonatype.org/publish/publish-guide/) cover probably 95% of what you need to know for this process, but there are a few _gotchas_ that I'll highlight below using the ❗ exclamation point emoji.

> Note: this guide assumes that your source code is hosted in a GitHub or GitLab repository.

## Steps

### 1. Create a Sonatype Jira issue

Sonatype syncs with Maven, and so to publish to Maven, you can publish via Sonatype. To do so, you'll need a Sonatype Jira account to create an issue. Do that by [clicking here to create an account](https://issues.sonatype.org/secure/Signup!default.jspa) and then [clicking here to create a Jira issue](https://issues.sonatype.org/secure/CreateIssue.jspa?issuetype=21&pid=10134).

As an example, [here is the ticket I opened](https://issues.sonatype.org/browse/OSSRH-71079) to publish a project of mine to Maven. If you want to publish multiple packages to Maven using Sonatype, you'll need to create multiple Jira tickets, but you only need the one user account.

The fields in the Jira are easy to fill out:

#### Summary

This should include the name of the project. In my case, I'm publishing a small project hosted at https://github.com/awwsmm/zepto, so I've included the name "zepto" in the Jira summary.

#### Group Id

If your project is hosted on GitHub, this should be something like `io.github.awwsmm`, or similar for your GitHub username. See [this guide](https://central.sonatype.org/publish/requirements/coordinates/) for more information on package coordinates.

> ❗ **GOTCHA:** this should _not_ be something like `com.github.awwsmm`. `com.github` coordinates are no longer supported. It _can_ be your personal website, like `com.awwsmm`, but [a bot will comment on your Jira asking you to add a DNS record to prove that you own that website, like here on another one of my Jiras](https://issues.sonatype.org/browse/OSSRH-95101).

#### Project URL

This is where users can go on the web to find information about your project. For me, that's `https://github.com/awwsmm/zepto`, but it could be a `github.io` page or a page on your personal website, or whatever.

#### SCM url

This is the URL that your source code is hosted at. For me, that's `https://github.com/awwsmm/zepto.git`.

### 2. Generate and distribute a PGP key

#### On macOS

On macOS, I recommend that you use https://gpgtools.org/ to create and distribute your PGP key. Simply download the installer and follow the instructions there.

To run `sbt publishSigned` later in this guide, you will also need `gpg2` and `pinentry` installed. You can get those on macOS via `brew` with

```bash
$ brew install gpg2
$ brew install pinentry-mac
```

Note that you need `gpg2` here, not `gpg`. You should [check if you have both installed and `brew uninstall gpg` if it exists](https://stackoverflow.com/a/45932796/2925434)

```bash
$ which gpg gpg2
```

Once you've done that, check that `gpg-agent` is correctly configured, and restart it by `--kill`ing it, per [these instructions](https://superuser.com/a/1628810/728488).

#### On Linux

We'll use a [PGP key](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) to sign this package, so users can be confident that you are the person who created it. To do this, you can mostly follow the instructions from [scala-sbt.org](https://www.scala-sbt.org/release/docs/Using-Sonatype.html)...

Install [GnuPG](https://www.gnupg.org/download/) (on macOS, you can do this via `brew install gnupg`) and verify that it's installed by checking the version

```bash
$ gpg --version
gpg (GnuPG) 2.3.1
...
```

Next, generate a key...

```bash
$ gpg --gen-key
```

...list your keys...

```bash
$ gpg --list-keys
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2023-07-11
/Users/andrew.watson/.gnupg/pubring.kbx
---------------------------------------
pub   ed25519 2021-07-11 [SC] [expires: 2023-07-11]
      1234517530FB96F147C6A146A326F592D39AAAAA
uid           [ultimate] Andrew Watson <my@email.com>
sub   cv25519 2021-07-11 [E] [expires: 2023-07-11]
```

...and distribute the key to some GPG keyserver, like

```bash
$ gpg --keyserver keyserver.ubuntu.com --send-keys 
1234517530FB96F147C6A146A326F592D39AAAAA
gpg: sending key A326F592D39AAAAA to hkp://keyserver.ubuntu.com
```

> ❗ **GOTCHA:** If you get an error like `keyserver send failed: No name` from the command above, it means the keyserver you're trying to send to is no longer active. [You can instead use any other major GPG keyserver](https://stackoverflow.com/a/68132500/2925434), like the Ubuntu one I used above.

[Leonard notes here](https://leonard.io/blog/2017/01/an-in-depth-guide-to-deploying-to-maven-central/) that synchronising these keys around the various keyservers can take some time, but for me it worked almost instantly.

Once you publish your key, you can check that it's visible on the public keyservers by searching for it here: https://keys.openpgp.org/.

### 3. Enable `sbt-pgp`

[As outlined here](https://www.scala-sbt.org/release/docs/Using-Sonatype.html), you'll next want to add the `sbt-pgp` plugin to your project. You can add it to your project's `plugin.sbt` file, or you can add it to `~/.sbt/1.0/plugins/gpg.sbt` to enable it for all sbt projects. The line you should add is

```scala
addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.2.1")
```

The latest version of this plugin can be found [at the GitHub page for the project](https://github.com/sbt/sbt-pgp).

### 4. Add your Sonatype credentials to your project

Next, add your credentials to your project by following the instructions in [Step 3](https://www.scala-sbt.org/release/docs/Using-Sonatype.html) here. I'll reproduce them to be clear...

Create a file at

```bash
$HOME/.sbt/1.0/sonatype.sbt
```

And add the following line to it

```scala
credentials += Credentials(Path.userHome / ".sbt" / "sonatype_credentials")
```

Then, create the credentials file at

```bash
~/.sbt/sonatype_credentials
```

Add the following information to that file

```
realm=Sonatype Nexus Repository Manager
host=s01.oss.sonatype.org
user=<your username>
password=<your password>
```

The `user` and `password` here are the same username and password you used when creating your account on Sonatype's Jira server in Step 1. You don't need to worry about putting anything in quotes here -- spaces are fine. But...

> ❗ **GOTCHA:** ...be careful! Some older guides say to set `host=oss.sonatype.org`, but this has recently changed to `host=s01.oss.sonatype.org`. More information about this change [can be found here](https://central.sonatype.org/publish/release/).

### 5. Set up your `publish.sbt`

The penultimate step in this process is to configure your project for publishing, by adding a bunch of information to either your project's `build.sbt` (or, as I recommend) `publish.sbt` file.

Replace `username` with your GitHub / GitLab username below, `project` with the name of the project (in my case, these are `awwsmm` and `zepto`, respectively), and all the other obvious fill-in bits, and paste it into a `publish.sbt` file at the root of your project

```scala
ThisBuild / organization := "io.github.username"
ThisBuild / organizationName := "username"
ThisBuild / organizationHomepage := Some(url("https://www.yourwebsite.com"))

ThisBuild / scmInfo := Some(
  ScmInfo(
    url("https://github.com/username/project"),
    "scm:git@github.username/project.git"
  )
)

ThisBuild / developers := List(
  Developer(
    id    = "username",
    name  = "Your Name Goes Here",
    email = "youremail@address.com",
    url   = url("https://www.yourwebsite.com")
  )
)

ThisBuild / description := "Describe your project here..."
ThisBuild / licenses := List("The Unlicense" -> new URL("https://unlicense.org/"))
ThisBuild / homepage := Some(url("https://github.com/username/project"))

// Remove all additional repository other than Maven Central from POM
ThisBuild / pomIncludeRepository := { _ => false }

ThisBuild / publishTo := {
  val nexus = "https://s01.oss.sonatype.org/"
  if (isSnapshot.value) Some("snapshots" at nexus + "content/repositories/snapshots")
  else Some("releases" at nexus + "service/local/staging/deploy/maven2")
}

ThisBuild / publishMavenStyle := true

ThisBuild / versionScheme := Some("early-semver")
```

You can set the `licenses` to whatever you feel is appropriate. Here is GitHub's guide to [choosing a license for your repo](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/licensing-a-repository) -- though be aware that they [probably ignore it](https://news.ycombinator.com/item?id=27736650) anyway.

> ❗ **GOTCHA:** Notice that we've also used `s01.oss.sonatype.org` above!

### 6. Publish!

Once you've got all of that set up, you should be able to publish your project from the `sbt` shell with the `publishSigned` command

```scala
sbt> publishSigned
```

On macOS, this should open up the GPGTools UI, where you can enter the password you associated with your PGP key. The output will then look something like

```bash
[info] Wrote /local/path/to/zepto_2.13-0.4.0.pom
[info] 	published zepto_2.13 to https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/io/github/awwsmm/zepto_2.13/0.4.0/zepto_2.13-0.4.0-sources.jar
[info] 	published zepto_2.13 to https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/io/github/awwsmm/zepto_2.13/0.4.0/zepto_2.13-0.4.0-javadoc.jar
[info] 	published zepto_2.13 to https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/io/github/awwsmm/zepto_2.13/0.4.0/zepto_2.13-0.4.0-javadoc.jar.asc
...
```

You can use your Sonatype username and password to log in to https://s01.oss.sonatype.org/ where you should now see your (pre-release) project!

Note that if you try to click on one of the `.jar` links above, you may get an error like

```
Staging of Repository within profile ID='...' is not yet started!
```

You can [follow along with Sonatype's guide here](https://central.sonatype.org/publish/release/) to release the artifacts to the public.

![Screenshot of my pre-release project listed in my account on sonatype.org](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ue4pc8kh7bmewm41qndl.png)

Select the project, click `Close` from the menu, and then `Release`. You should see your project [on Maven](https://repo1.maven.org/maven2/io/github/awwsmm/zepto_2.13/0.4.0/) almost immediately, though it will take a few hours to show up [in the search engine](https://search.maven.org/artifact/io.github.awwsmm/zepto_2.13).

...and that's it!

You should now be able to import your published library into other projects by adding

```
"io.github.awwsmm" %% "zepto" % "0.4.0"
```

(or whatever is appropriate) to the `libraryDependencies` in the `build.sbt` of another project.

Publish your Scala sbt Project to Maven in 5 Minutes with Sonatype

A Case Study in Building a Website using Next.js


## Trade-Offs in Software Development

> "Where's all my CPU and memory gone?"
>
> -- [thegeomaster](https://news.ycombinator.com/item?id=14868999)

### Software development is -- and has always been -- about trade-offs.

The [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem) tells us that we need to choose between consistency, availability, and partition tolerance when designing distributed data stores.

[Caches](https://www.indeed.com/career-advice/career-development/cache-pros-and-cons) can make information available more quickly, but it might be out of date, and it will definitely use more storage space than making a fresh request each time.

And, as always, money can be a factor. [SSDs are faster than HDDs](https://reviewed.usatoday.com/laptops/features/ssd-vs-hdd), but they are more expensive per GB. And microservices in a distributed system should each have their own database, but cloud computing costs can mean that shared DBs are more cost-effective.

Weighing the pros and cons of varied solutions to a problem was something I needed to tackle recently when redesigning part of my personal website, [awwsmm.com](https://awwsmm.com). Here's how that went down...

## A Case Study: My Website

### The Setup

My website is a pretty minimal Next.js site, written in TypeScript, hosted [on GitHub](https://github.com/awwsmm/awwsmm.com), built and deployed [by Vercel](https://vercel.com/).

In general, Next.js allows you to have two kinds of pages: static pre-rendered pages, and dynamic pages, rendered "just in time", when a visitor to your website tries to visit that page.

My website has static [blog posts](https://www.awwsmm.com/blog), as well as ["project" pages](https://www.awwsmm.com/projects), which give a quick overview of personal projects that I've been working on lately.

My initial design was for a given project page (for example, [this one for my website itself](https://www.awwsmm.com/projects/awwsmm.com)) to have an up-to-date commit history, interleaved with occasional "log entries", summarizing big sweeping changes made to these projects. (Kind of like release notes, but with more detail behind _why_ certain changes are being made.)

So what was the problem?

### The Problem

The problem was that these project pages were statically rendered; they were built in advance.

I would [request the commit history of a project from GitHub](https://github.com/awwsmm/awwsmm.com/blob/cfec0c66a0cf1ba8cc54459ee77c85b707d21d61/lib/utils/ProjectUtils.ts#L59) and write it to a local cache, saved in the repository.

When [a new PR is opened](https://github.com/awwsmm/awwsmm.com/pull/74) against the repo containing my website, Vercel runs a test deployment. When the test deployment looks good, I hit "merge" and the new changes are added to the repo in a merge commit.

But, because the cache is created only when I'm developing locally, _this merge commit is not a part of the commit history in the cache._ It couldn't possibly be. It would require updating the cache file, which would introduce changes not included in that commit, which would require another commit, ad infinitum.

This means that the commit history for the `awwsmm.com` project page is _always_ at least one commit behind `master`.

This bothered me, and I wanted to see if I could fix it.

### First Attempt: Environment-Aware Caching

[My first attempt at a solution](https://github.com/awwsmm/awwsmm.com/commit/569a6368f7bd115a13aa219b398b4bf23eab04ad#diff-e1998422d9b0a8903593c437a2bf074f2d47e10bede05c333e3a2312797ca486) was (what I'm going to call) "environment-aware caching".

What if, after the deployment passed and the new PR was merged into `master`, Vercel ignored the cache, only using it as a backup? During deployment, we could hit the GitHub API again, which should then have the new commit, right?

This required knowing which environment the build was running on. This is straightforward, as Vercel populates [a `VERCEL_ENV` environment variable](https://vercel.com/docs/concepts/projects/environment-variables/system-environment-variables) to `"production"`, `"preview"`, or `"deployment"`, depending on where the build is running.

But this also required maintaining a cache which we hopefully would never fall back to, which seemed kind of silly.

It also meant that each release would have to be deployed at least twice: once to satisfy the checks before merging the PR, and once after the PR was merged to pick up the new commit on `master`. I'd have to remember to do this "double deployment" to keep things up-to-date.

Finally, there was some human error here in that I tried to use [the same caching mechanism for "last updated" dates on my blog posts](https://github.com/awwsmm/awwsmm.com/commit/cb38f6411859de4586f945eaae6231ebcd87a78f#diff-8779cf4bd89603a2f8a50f4ea24460afbd79e6d8b65ba8575183d02f47cf074b), confusing the issue.

All in all, this solution was pretty complex to maintain (all I want is a static blog), and it put me off of keeping my website up-to-date for a while. When I finally came back here after a few months, I decided that a simpler solution was in order.

### Second Attempt: Server-Side Rendering

So how about trying to [render the project pages "just in time"?](https://github.com/awwsmm/awwsmm.com/commit/5daf1b29cbdcafa7f26f6fed340adbfc6482df2e#diff-dc938814c5900cd48c67f3c5b743ac02c3d0730245e9fa633d02e9fef4cdb801R104)

Vercel's [server-side rendering (SSR)](https://vercel.com/blog/nextjs-server-side-rendering-vs-static-generation) also generates static pages, but it renders them only when the user navigates to the page, not during deployment.

"This is great!" I thought. I could just request the commit history when the page is requested, and it would always be up-to-date.

Unfortunately, requesting and processing 100 commits from GitHub seemed to be too much to ask. I was consistently waiting about 3 seconds for the page to load, which is [really bad](https://web.dev/ttfb/). Project pages with shorter commit histories loaded a bit faster, but there was still a noticeable delay. Sending the request to GitHub, awaiting a response, processing the response, generating the resulting page, and displaying it just took too much time.

This approach would also send a request to GitHub _every time_ a user loaded that page.

This second issue could be solved by [fine-tuning the `Cache-Control`](https://github.com/awwsmm/awwsmm.com/commit/d6eb611eb5d9c746670cceeffc0fecfe32fd0817#diff-dc938814c5900cd48c67f3c5b743ac02c3d0730245e9fa633d02e9fef4cdb801R105-R123) header sent along with the request, such that I could guarantee that the 5000-requests-per-hour (authenticated) limit would never be exceeded.

But the first issue remained a problem.

### Third Attempt: Non-Blocking Server-Side Rendering

"Maybe I'm the problem" I thought.

"Maybe it's the way I (think I) am blocking inside of `getServerSideProps`."

[I rearranged this method](https://github.com/awwsmm/awwsmm.com/commit/ea8ec00ed8905f55d6bb780df5535dcb459af638) to not `await` anywhere, but return a `Promise` which is a result of other `Promise`s chained together with `then`, and nothing else.

I was hoping that, with everything done in a non-blocking way in the return value, Vercel could work some magic to speed up the call. (Maybe it could run the request as soon as the user _hovered over_ the link to the page?)

But it didn't help. I was still stuck at ~3 seconds of loading time. Worth a try, at least.

### Fourth Attempt: GraphQL

"Maybe the response from GitHub is taking so long because it's returning too much data?"

I wasn't using _most_ of the response anyway; all I cared about was the commit hash, the message, and the date. I'd never used GraphQL before, but I knew that it could be used in situations like this, where you wanted to request only _particular_ data from an endpoint.

So I learned enough about GraphQL and GitHub's API to [request only the commit data I cared about](https://github.com/awwsmm/awwsmm.com/commit/f6260bbc9bd1d181fbf3f613a73008f1cfe53e4c#diff-93b7ed2c3a46038993bf9d2c1478cc9dbb3f14e3beeafd30cb21983fbfc75befR67-R79).

This sped up the page a bit _locally_ but not in production on Vercel. It was still taking about 3 seconds.

### Fifth Attempt: Timeout / Fallback to Cache

"Well, if it's loading fast enough locally, but not remotely, maybe I can set a timeout threshold?"

My thought was that I could [cache](https://www.google.com/search?q=time+is+a+flat+circle) a "stale" version of the page to display if the "live" version of the page took too long to load. Maybe longer than 500ms or so.

So I would now [generate a cache when building locally](https://github.com/awwsmm/awwsmm.com/commit/927db29fb8cdfb53402d8a7aeff047503ec36ff1#diff-93b7ed2c3a46038993bf9d2c1478cc9dbb3f14e3beeafd30cb21983fbfc75bef), and save the cache to the repo. In production, I would attempt to request fresh data from GitHub, but if it took longer than 500ms, I would fall back to the cache.

...but it still took 3 seconds to render the page remotely.

"Why?" I thought, pulling my hair out in frustration.

Other project pages loaded quickly... maybe Vercel was just (somwehow?) slow to process this 600-line JSON file, generate the hundreds of components for it, style all of them, and display them.

I found [issues on the `vercel` repo](https://github.com/vercel/vercel/discussions/7961) of people complaining about similar problems. Maybe it just took a few seconds for Vercel to spin up a runner to render the page? (That didn't seem to square with the load times of the other project pages.)

I took solace in the fact that other people on the Internet _also_ thought that [`getServerSideProps` is weird](https://www.youtube.com/watch?v=1er7Zqs_h9k) and unintuitive.

I assessed other possible avenues for investigation: [timing the response?](https://web.dev/custom-metrics/?utm_source=devtools#server-timing-api), [actually reading the docs? (no thanks)](https://vercel.com/blog/nextjs-server-side-rendering-vs-static-generation), incremental static generation?, [edge functions?](https://vercel.com/docs/concepts/functions/edge-functions).

I was beginning to lose the will to live... all I wanted was a blog.

## Regrouping

I took a breather and came back to it all after a little while.

"What is it I actually want?"

- up-to-date commit histories
- fast page loads

The problem was that those two things were -- if not mutually exclusive, at least -- in competition with each other. Up-to-the-second commit histories would require a request to GitHub as soon as the user requested the project page. Which meant that all of the data fetching, and processing, and rendering would have to be done _quickly_.

This didn't seem like too big of an ask to me, but apparently it was. Maybe it was my code, maybe it was the Lambda cold start times, maybe it was something on Vercel's end... whatever it was, it was pinning me to 3-second page load times.

"Maybe I can request and process _most_ of the history in advance, then only request _recent_ history when a user clicks on a page?"

This sounded overcomplicated, though. (Unlikely, but) what if a project had had 100 new commits since I last deployed my website (and generated the cache)? Then I would have the same problem: trying to request and render 100 commits onto this history page.

[So I compromised](https://github.com/awwsmm/awwsmm.com/commit/34ee82581280b28da6041b4966da0d423665b885), and came up with a simpler solution:

1. generate `project/` pages statically

   This solves the load time issue -- by the time we get to production, the pages will have already been generated, so nothing needs to be done except displaying them.
   
   But this means that we will not have an up-to-date commit history.

2. accept that the commit history will not be up-to-date

   I'd already sunk so much time into this, I was ready to compromise.

   Nobody coming to my website will care if my commit histories are slightly out of date. So I decided to just put a disclaimer at the top and bottom of the histories, saying something like "for the most up-to-date commit history, see GitHub".

Now, we can generate pages in advance, keep load times to basically zero, and we don't have to worry about complex caching solutions, or what environment the build is running in, or GitHub rate limits, or anything.

My compromise was that my time and energy were worth more to me than having this one feature on my website be exactly the way I had envisioned it initially.

## Software Development is About Compromise

In my case, I tried and tried to get my website to do what I wanted it to, but my two requirements: up-to-date commit histories and fast loading times, were in direct competition with each other.

Having an up-to-date history will require a request when the user clicks the button, and processing the result of that request, which will take time.

Surely there are more complex solutions which balance these two better, but in the end, having these pages be up-to-date is not critical for my blog. Choosing where to use my time is another trade-off. I learned a lot about Vercel, GraphQL, and Promises in JavaScript / TypeScript during this process, but ultimately, "see GitHub" is good enough for me. And that's a compromise I'm willing to accept.

Software Development is About Compromise

Ergonomic Multi-Line Strings for bash, zsh, and Other Shells


## The State of Multi-Line Strings

Multi-line strings in shells are a pain.

Suppose you want to create a file, using a shell script, which contains the following content

```ts
export default class Greeter {
  greet(name: string) { return 'Hello, ' + name + '!'; }
}
```

How can this be achieved?

### Some Methods

#### Method 1: a multi-line variable

This simple solution works when the variable definition is not indented at all

```sh
var="export default class Greeter {
  greet(name: string) { return 'Hello, ' + name + '!'; }
}"
```

```
$ echo $var
export default class Greeter {
  greet(name: string) { return 'Hello, ' + name + '!'; }
}
```

But what if we're defining `$var` within a function, and we want it indented along with the rest of the function body?

```sh
function my_function() {
  var="export default class Greeter {
    greet(name: string) { return 'Hello, ' + name + '!'; }
  }"
  echo $var
}
```

```sh
$ my_function
export default class Greeter {
    greet(name: string) { return 'Hello, ' + name + '!'; }
  }
```

Oh, well, that's obviously not what we want.

So, simple variable assignment: it works in a very limited subset of cases, when the variable definition is not indented at all. Let's try another method.

#### Method 2: a single-line variable with '`\n`'s for line breaks

In this method, we replace all of the line breaks in the multiline string with `\n` line break characters:

```sh
function my_function() {
  var="export default class Greeter {\n  greet(name: string) { return 'Hello, ' + name + '!'; }\n}"
  echo $var
}
```

```sh
$ my_function
export default class Greeter {
  greet(name: string) { return 'Hello, ' + name + '!'; }
}
```

The result looks good, but the method is messy. What if we want to reformat this like

```ts
export default class Greeter {
  greet(name: string) {
    return 'Hello, ' + name + '!';
  }
}
```

That would involve adding more `\n` characters, and spaces to match the indentation. It's not extremely straightforward:

```sh
function my_function() {
  var="export default class Greeter {\n  greet(name: string) {\n    return 'Hello, ' + name + '!';\n  }\n}"
  echo $var
}
```

So, explicit line break characters: this works if the text you want formatted won't change often, and if the readability of the implementation doesn't matter. If you want the text-generating code itself to be readable or maintainable, this is not a great solution.

So what else can we do?

#### Method 3: Heredocs

Multiline strings are what [Heredocs](https://en.wikipedia.org/wiki/Here_document) were made for:

> In computing, a here document (here-document, here-text, heredoc, hereis, here-string or here-script) is a file literal or input stream literal: it is a section of a source code file that is treated as if it were a separate file. The term is also used for a form of multiline string literals that use similar syntax, preserving line breaks and other whitespace (including indentation) in the text.

So let's see how well they work for our problem

```sh
function my_function() {
  var=$(cat <<EOF
  export default class Greeter {
    greet(name: string) { return 'Hello, ' + name + '!'; }
  }
  EOF)
  echo $var
}
```

```sh
$ my_function
/Users/andrew/test.sh:8: parse error near `var=$(cat <<EOF'
```

Oh, uh, yeah, obviously the delimiter sequence (`EOF` in this case), cannot be indented, and must appear on a line by itself, so we have to write

```sh
function my_function() {
  var=$(cat <<EOF
  export default class Greeter {
    greet(name: string) { return 'Hello, ' + name + '!'; }
  }
EOF
  )
  echo $var
}
```

...which is fine, but sort of breaks indentation of the rest of the function body. It also doesn't work:

```sh
$ my_function
  export default class Greeter {
    greet(name: string) { return 'Hello, ' + name + '!'; }
  }
```

Just like Method #1, this method adds to the output the whitespace we used to indent the function body, which we don't want.

So how can we preserve _only_ the indentation _we want_ (and maybe get rid of that ugly heredoc delimiter)?

### My Method

Here's how I do it

```sh
function my_function() {
  var="$(sed -e 's/^[ ]*\| //g' -e '1d;$d' <<'--------------------'
    | 
    | export default class Greeter {
    |   greet(name: string) { return `Hello, ${name}!`; }
    | }
    | 
--------------------
    )"
  echo $var
}
```

I use pipe characters `|` to define a "margin", which I then strip out using `sed`. `sed -e 's/^[ ]*\| //g'` will remove any number of space characters (`[ ]*`) at the beginning of the line (`^`), followed by a pipe (`|`), followed by one space character (`[ ]`).

> This "margin" method was inspired by [Scala's `String#stripMargin` functionality](https://www.oreilly.com/library/view/scala-cookbook/9781449340292/ch01s03.html), which behaves in a very similar way.

The second `sed` expression, `-e '1d;$d'`, removes the first and last line. I add blank lines to provide a bit of visual whitespace around the content I want to write to the variable. If you don't want one or both of these blank lines, remove them with this slight variation on my method

```sh
function my_function() {
  var="$(sed -e 's/^[ ]*\| //g' <<'--------------------'
    | export default class Greeter {
    |   greet(name: string) { return `Hello, ${name}!`; }
    | }
--------------------
    )"
  echo $var
}
```

I don't mind the line of hyphens, either, as the `EOF` replacement, because it sort of acts like the top and bottom margin of the content. But, if you put the heredoc delimiter in quotes, as I have above, you can also include whitespace in it. So you could do something like

```sh
function my_function() {
  var="$(sed -e 's/^[ ]*\| //g' <<'    +'
    | export default class Greeter {
    |   greet(name: string) { return `Hello, ${name}!`; }
    | }
    +
    )"
  echo $var
}
```

Though I personally think this leaves a bit too much whitespace under the content. Also, many syntax highlighting algorithms have trouble with this.

With any of these variations, you can indent the content to whatever level you like

```sh
function my_function_1() {
  var="$(sed -e 's/^[ ]*\| //g' <<'--------------------'
    | export default class Greeter {
    |   greet(name: string) { return `Hello, ${name}!`; }
    | }
--------------------
    )"
  echo $var
}

function my_function_2() {
  var="$(sed -e 's/^[ ]*\| //g' <<'--------------------'
| export default class Greeter {
|   greet(name: string) { return `Hello, ${name}!`; }
| }
--------------------
    )"
  echo $var
}

function my_function_3() {
  var="$(sed -e 's/^[ ]*\| //g' <<'--------------------'
              | export default class Greeter {
              |   greet(name: string) { return `Hello, ${name}!`; }
              | }
--------------------
    )"
  echo $var
}
```

```sh
$ my_function_1; my_function_2; my_function_3
export default class Greeter {
  greet(name: string) { return `Hello, ${name}!`; }
}
export default class Greeter {
  greet(name: string) { return `Hello, ${name}!`; }
}
export default class Greeter {
  greet(name: string) { return `Hello, ${name}!`; }
}
```

The flexibility -- combined with the visual aesthetics -- of this method is why it's recently become my go-to for multi-line strings in the shell.

Elegant Multi-Line Shell Strings

Debugging a New Feature in a Vercel TypeScript GitHub Repo


**Part III: The Deep End**

At this point, I wasn't sure where to go next.

Why should [these blog posts now have a seemingly random publication date](https://www.awwsmm.com/blog/whats-wrong-this-time-part-2), which was not the current date, and was not the date they were first added to the repo? What was going on?

So I did what most programmers do in a situation like this: I added some `console.log()`s.

## Digging Deeper

I wanted to know what commits were available, and what information they had. In other words, I wanted better [_observability_](https://dzone.com/articles/rethinking-programming-automated-observability) into what was going on in this bit of the codebase.

My first idea was to just [print out the dates of every line returned from `git log`](https://github.com/awwsmm/awwsmm.com/commit/a43bf7c356aa4b649ddfbf26528a454ae94bd807). The output of that (for a given blog post) looked something like

```
lines returned from git log
2022-01-09T20:48:23+00:00
2022-01-06T09:18:41+00:00
```

...okay, not extremely useful. Why are there only two commits here? This is just the same information we had on the website. Maybe [printing out the hash of each commit](https://github.com/awwsmm/awwsmm.com/commit/0477f384c0cb604c8cd4b64307c1b37b150575dc) would be a bit more helpful? Then I could check if there was anything unusual about these commits

```
lines returned from git log
69e038a919e448251fa2211a9fcf3fda914812fe @ 2022-01-09T20:48:23+00:00
d5cf8fbc05891ac9d8d7067b5cb1fb195dc2cf99 @ 2022-01-06T09:18:41+00:00
```

Now we can search GitHub for that commit [`dc2cf99`](https://github.com/awwsmm/awwsmm.com/commit/d5cf8fbc05891ac9d8d7067b5cb1fb195dc2cf99).

But this commit doesn't add or update _any_ blog posts... so why is it being returned from `git log <path/to/blogpost>`?

What if I `git log`ged a file that has _definitely_ been around since the first commit, like `index.tsx`. I tried printing out every log line for this file and saw the following on Vercel

```
lines returned from git log index.tsx
69e038a919e448251fa2211a9fcf3fda914812fe @ 2022-01-09T20:48:23+00:00
88c420835d35a008de808b7cef04980a15b029bc @ 2022-01-09T12:55:49+00:00
0a882cf5062e4c0ac4505ed609ca77f14b35a76a @ 2022-01-08T20:15:44+00:00
d4a9a360c38398cdd41825aa0fe193e8176cb4fd @ 2022-01-07T22:41:52+00:00
3acb76c1f6c6d1b4cdb76939496e251220aa29ea @ 2022-01-06T20:09:17+00:00
```

It only goes back five commits! The commit history looked the same for other long-lived files as well. Only ever going back to that last commit on January 6.

Running the same code on my local machine gives many more commits, going back all the way to the first commit on January 2.

What gives?

## The Shallow End

At this point, I wasn't sure how much more debugging I could do. So I started doing a bit of research.

And I found [this issue ("How to unshallow repo?")](https://github.com/vercel/vercel/discussions/5737) on the Vercel GitHub repo

> _"Hello, I need to define a variable at build time that depends on `git describe` which depends on git history, but it seems the repo in vercel build enviroment is a shallow clone with only few last commits."_

That sounds like my problem! And it sounds like it's caused by Vercel making [a _shallow clone_ of my git repo](https://www.perforce.com/blog/vcs/git-beyond-basics-using-shallow-clones) before building. I'd never encountered shallow cloning _in the wild_ before, but I knew of it as a concept, which is how I found that GitHub issue.

So how can we work around this? We simply won't have the information available at build time to determine the correct "published" and "last updated" dates for a given blog post.

But there's always a way to work around these kinds of limitations. In this case, that involves a cache.

## Cache Rules Everything Around Me

There are a few ways we could solve this problem. We could, for instance, use the GitHub API to pull commit information from the repo hosted on GitHub.com. I chose not to do this as I preferred to keep the solution self-contained: we have all the information available at build time _when running locally_, so how could we make that information available when building _for production_ (on Vercel), as well? (Where we'll have a shallow clone of the repo.)

Rather than make API calls over the internet for information which is available locally, I thought we could simply save this information in a cache, and then use that cache when building on Vercel.

The workflow I came up with for writing blog posts (and caching the important git info) looked something like this

1. draft a `wip-` post (these are [ignored for version control by my `.gitignore`](https://github.com/awwsmm/awwsmm.com/blob/4281812447b58b08bcd613530e4d8db2b1855be6/.gitignore#L23))
2. when the draft is ready, `git commit` it to the `development` branch and push to Vercel
3. for...
    - new blog posts (where the only commit in `git log` is the current commit), Vercel assumes the post is brand-new and uses the date of the current commit for the "published" and "last updated" times
    - old blog posts (where more than one commit references this blog post), Vercel looks for cached "published" and "last updated" times, and throws an error if it doesn't find any

There are a few small problems with this.

First, when do we update the cache? You'll notice that there is no step in the workflow above for ensuring that the cache is up-to-date. Since we only have access to the required information when building locally, we have to update the cache when building locally. But when does this information get pushed to the remote repo? We have to enforce that, as well.

Second, the above workflow has a problem when we merge the `development` branch into the `master` branch when promoting a new release to production -- the merge commit itself means that the "new" blog post is now in two commits. As outlined above, this will cause Vercel to throw an error if the post isn't in the cache (it won't be).

## So... What Now?

I've got some hacky fixes for the above problems implemented.

For instance, I've got a [pre-push git hook](https://github.com/awwsmm/awwsmm.com/blob/4281812447b58b08bcd613530e4d8db2b1855be6/git-hooks/pre-push) which runs a build before each `git push`. This means that -- in theory -- the cache is always up to date. But of course, I need to make sure to `git add` it in the _next_ commit.

As for the "merging creates a new commit" issue, I've tried two solutions so far.

The first was to distinguish between commits on the `development` branch and commits on the `master` branch. Only blog posts with commits on `master` should be considered as "old". This works great when running locally, but the clone that Vercel creates seems to _rename_ this `development` branch to `master` when building a preview deployment. So that's a no-go.

The second solution (which I'm currently using) is to simply [ignore merge commits](https://github.com/awwsmm/awwsmm.com/blob/4281812447b58b08bcd613530e4d8db2b1855be6/lib/blog/SlugFactory.ts#L28).

So far, the above appears to be working. But it feels like an overly complex and fragile solution, and I hope to improve upon it in the future. Maybe just querying GitHub for the commit history is easier than going through all of this cache trouble.

## Conclusion

So that's it! The goal was simple: get rid of arbitrary "published" times on blog posts and pull that data directly from the project's git history. But the solution ended up being much more complex and nuanced than I had initially planned.

But along the way, I learned some new tools and tricks, I learned a bit more about how my repo is built and deployed on Vercel, and I have some ideas for how I can make things more streamlined in the future. And that's what this is all meant to be, really, a learning experience.

In the future, maybe I'll do away with this overly-complex caching mechanism, but I do want to get the "published" and "last updated" dates from the repo's git history. This initial solution, while messy, does the job for now.

What's Wrong This Time? Part III: The Deep End


**Part II: The Bugs**

There's an old programming joke that goes [something like](https://martinfowler.com/bliki/TwoHardThings.html)

> _There are only two hard problems in computer science: cache invalidation, naming things, and off-by-one errors._

I think we should add a third (fourth?) problem to that list: sorting things.

## Sorting Things

There are [lots of different ways to sort things](https://en.wikipedia.org/wiki/Sorting_algorithm) in computer science. C.S. students learn about time and space complexity of these sorting algorithms, YouTubers make [cool visualisations](https://www.youtube.com/watch?v=BeoCbJPuvSE) of them, and occasionally, [a guy named Tim](https://en.wikipedia.org/wiki/Timsort) will invent a new one.

But there's one aspect of sorting algorithms that -- for me, at least -- seems completely impossible: remembering in which direction things are sorted.

If you say to a group of people: "okay, everyone, stand in a single-file line, ordered by height", the next question you might ask is "okay, but in which direction?" Who should stand at the _front_ of the line? The shortest person or the tallest person?

In programming, we define comparison functions, which describe how to order whatever objects we're interested in.

Some comparison functions seem obvious. For example, in TypeScript, using the default `string` comparison...

```ts
const array: string[] = ["cherry", "apple", "banana"]
array.sort()
//...
```

...we would expect `array` to be sorted alphabetically, with `apple` as the first (`0`th) element of the sorted array

```ts
//...
console.log(array)    // [ 'apple', 'banana', 'cherry' ]
console.log(array[0]) // apple
```

> Note that `<array>.sort()` in JavaScript sorts the array "in place", so that the original, unsorted `array` no longer exists afterward. In some languages, and for some sorting algorithms, arrays are not sorted in place, and a new array will be returned. This new array should be assigned to a new variable.

But often we will be working with objects more complex than `string`s, and we will need to define custom comparison functions. These are functions which take two elements of type `T` and return a `number`, and are used to sort arrays of type `T`:

```ts
type T = string

const newArray: T[] = ["cherry", "apple", "banana"]

function comparison(t1: T, t2: T): number {
  return t1.charCodeAt(0) - t2.charCodeAt(0)
}

newArray.sort(comparison)

console.log(newArray)    // ?
console.log(newArray[0]) // ?
```

Without [reading the docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), will the `console.log()`s above give the same result as the earlier ones? How about something a bit simpler -- sorting an array of `number`s:

```ts
type T = number

const newArray: T[] = [42, 2112, 19]

function comparison(t1: T, t2: T): number {
  return t2 - t1
}

newArray.sort(comparison)

console.log(newArray)    // ?
console.log(newArray[0]) // ?
```

Will the first element above be `19`? Or `2112`? Are you sure?

I understand the utility of sorting algorithms, and I understand the need for a ternary (greater than, less than, or equal) return value, and hence `number` as the return type instead of `boolean`, but comparison functions are just one of those things that I've always had to test every time. Sometimes in development, and sometimes in production.

## So What Happened?

With what we learned above, you should now be able to see what went wrong with [my initial code](https://github.com/awwsmm/awwsmm.com/commit/69e038a919e448251fa2211a9fcf3fda914812fe). The problem was here

```ts
    // get the blog post date from its git commit date
    const gitLog = SlugFactory.git.log({ file: `blog/${slug.params.slug}.md` });

    return gitLog.then(lines => {
      const dates = lines.all.map(each => each.date);

      // if blog post hasn't been committed yet, use current date
      const date = dates[0] ?? new Date().toISOString();

      return new FrontMatter(slug.params.slug, title, description, date, rawContent);
    });
```

`git log` returns commits sorted by date, such that _newer_ commits come first and _later_ commits come afterward. So `dates[0]`, above, is the _newest commit_ returned from `git log`, and each blog post was being given a "publication" date of the most recent commit in which that post was modified.

When were these blog posts most recently modified? Well, all of them were modified in [that same commit](https://github.com/awwsmm/awwsmm.com/commit/69e038a919e448251fa2211a9fcf3fda914812fe), because the point of the commit was to remove the `date` parameter from the front matter. Essentially, I was mixing up the `lastUpdated` date and the `published` date. One of these is the first element in the list (`dates[0]`) and one of them is the last element in the list (`dates[dates.length-1]`).

So like I said, there are four hard problems in computer science.

## On To The Next One

With that fixed, we're off to the races, right?

![Screenshot from awwsmm.com showing blog posts with incorrect dates](https://i.imgur.com/ME7yZQ9.png)

Oh... well, that's not right.

Those two posts were both committed on January 2 ([Hello, World!](https://github.com/awwsmm/awwsmm.com/commit/ec96618d38c71134f4a9ed14d6ae6d7a2b5c9e59) and [Git Hooks](https://github.com/awwsmm/awwsmm.com/commit/b2e504f52e4df0ddf77c662903e39b4aaf12f242)), not on January 6. So why did they both have the wrong date?

That's right, it's another bug... Or is it?

Find out in [the _thrilling_ final installation of this debugging mystery!](https://www.awwsmm.com/blog/whats-wrong-this-time-part-3)

What's Wrong This Time? Part II: Electric Bugaloo


**Part I: The Idea**

## _"I have an idea"_*, I said to myself.

"What if, instead of adding arbitrary dates to blog posts as I write them, I just got the dates from git?"

> [Git](https://git-scm.com/) is a [version control system](https://www.atlassian.com/git/tutorials/what-is-version-control) used by software developers which tracks changes to files, as well as creation and deletion of files. Every change, addition, or deletion is timestamped and has a [hash](https://en.wikipedia.org/wiki/Hash_function) which uniquely identifies those changes, like a fingerprint.

"[Each git commit](https://github.com/awwsmm/awwsmm.com/commits/master) has a date, so I should be able to programatically determine when a file in my [repo](https://www.gitkraken.com/learn/git/tutorials/what-is-a-git-repository) was added, or edited."

That was my idea for simplifying the metadata ("front matter") that I add to each of my blog post files on [my website](https://github.com/awwsmm/awwsmm.com). Before this adventure, that metadata looked [something like this](https://raw.githubusercontent.com/awwsmm/awwsmm.com/ec96618d38c71134f4a9ed14d6ae6d7a2b5c9e59/blog/hello-world.md):

```txt
---
title: 'Hello, World!'
description: 'Rewriting My Personal Website in Next.js and TypeScript'
date: '2022-01-01'
---
```

What I wanted to do was get rid of that arbitrary `date` field I was adding to every blog post, and just let git tell me when I published or updated a file. I could pull this information from the history of file changes that git keeps track of.

Sounds relatively simple, right?

Well, there were a few roadblocks to getting this up and running. Before we get into them, let's take a look at my initial, quick-and-dirty solution.

## First Attempt

### Git background

When working locally (on your personal computer), you can interact with git using the command line. One command, [`git log`](https://git-scm.com/docs/git-log), gives a list of all of the changes saved ("committed") to the project

```txt
$ git log --oneline -n 5
b6eea85 (HEAD -> master, origin/master, origin/HEAD) Merge pull request #15 from awwsmm/development
bc222b3 (origin/development, development) automatically date blog posts using git history
88c4208 order blog posts on index page reverse chronologically
9368f24 new blog post about nominal, structural, and duck typing
6bbe307 Merge pull request #1 from awwsmm/development
```

The options I passed to `git log`, `--oneline` and `-n 5`, tell git that I only want one line of minimal information for each commit (just the hash and the first line of the commit message), and that I only want the five most recent commits. By default, git shows something like

```txt
$ git log
commit b6eea85256fe54f34013f17aca4e892aba0778dd (HEAD -> master, origin/master, origin/HEAD)
Merge: 88c4208 bc222b3
Author: Andrew <aww@awwsmm.com>
Date:   Fri Jan 14 19:01:11 2022 +0000

    Merge pull request #15 from awwsmm/development

    automatically date blog posts using git history
```

...with the commit hash, the commit message, the date of the commit, the author, and so on. But lots of other options can be set for `git log`, for instance, specifying a hash will show only that commit and its ancestors (commits that came before it), and `--name-only` shows the names of all files modified in that commit

```txt
$ git log bc222b3 --name-only -n 1
commit bc222b37913ec2cdd7ff5f152dfaca06d33ec9f3 (origin/development, development)
Author: Andrew Watson <aww@awwsmm.com>
Date:   Fri Jan 14 18:54:39 2022 +0000

    automatically date blog posts using git history

.gitignore
README.md
blog/cache.json
blog/git-commit-hooks.md
blog/hello-world.md
blog/nominal-vs-structural-vs-duck-typing.md
lib/blog/FrontMatterFactory.ts
lib/blog/SlugFactory.ts
package-lock.json
package.json
pages/blog/[slug].tsx
pages/index.tsx
```

You can also pass a file path to `git log` and it will only show you commits in which that file was modified

```txt
$ git log blog/hello-world.md
commit bc222b37913ec2cdd7ff5f152dfaca06d33ec9f3 (origin/development, development)
Author: Andrew Watson <aww@awwsmm.com>
Date:   Fri Jan 14 18:54:39 2022 +0000

    automatically date blog posts using git history

commit ec96618d38c71134f4a9ed14d6ae6d7a2b5c9e59
Author: Andrew Watson <aww@awwsmm.com>
Date:   Sun Jan 2 12:11:54 2022 +0000

    attempting to deploy to Vercel
```

That's all well and good, but I wanted to get this information when building my website, which is written in TypeScript. So I would need a TypeScript or a JavaScript library to be able to do this easily. That's where [`simple-git`](https://www.npmjs.com/package/simple-git) comes in.

### Git in TypeScript

`simple-git` is a JavaScript library which [allows you to run git commands](https://github.com/steveukx/git-js) from within TypeScript / JavaScript code.

For instance, instead of the above `git log blog/hello-world.md`, we can write something like

```ts
import simpleGit from 'simple-git'

const git = simpleGit()
const logResult = await git.log({ file: 'blog/hello-world.md' })
const commits = logResult.all
```

Then, we can loop over all commits and easily access each commit's data

```ts
commits.forEach(commit => {        // example:
  console.log(commit.author_email) // aww@awwsmm.com
  console.log(commit.author_name)  // Andrew Watson
  console.log(commit.body)         //
  console.log(commit.date)         // 2022-01-14T18:54:39+00:00
  console.log(commit.diff)         // null
  console.log(commit.hash)         // bc222b37913ec2cdd7ff5f152dfaca06d33ec9f3
  console.log(commit.message)      // automatically date blog posts using git history
  console.log(commit.refs)         // origin/development, development
})
```

So that should be it: when compiling the project, we should be able to use this library to get all log lines which refer to a specific file. The most recent one should be the `lastUpdated` date of the file, while the least recent one should be the `published` date of the file.

[I quickly coded this up](https://github.com/awwsmm/awwsmm.com/commit/69e038a919e448251fa2211a9fcf3fda914812fe), ran it locally, and everything looked fine. I thought that would be the end of the story.

But then I pushed it to production.

## First Problem

The first problem I hit was that all of my blog posts now had the same date (which at the time was the current date):

![Screenshot of awwsmm.com showing multiple blog posts with the same date](https://i.imgur.com/C0WGWdp.png)

Do you see any problems with [the code I wrote here?](https://github.com/awwsmm/awwsmm.com/commit/69e038a919e448251fa2211a9fcf3fda914812fe)

What's going on here?

Check out the answer in [the second part of this series](https://www.awwsmm.com/blog/whats-wrong-this-time-part-2).

---

> \* This is the traditional phrase for conjuring bugs in your programs. See also: _"I'll just do a little refactoring"_.

What's Wrong This Time? A Debugging Mystery in Three Parts

Nominal, Structural, and Duck Typing in Java, TypeScript, and JavaScript


## Nominal Typing

Most major programming languages with objects use [nominal typing](https://en.wikipedia.org/wiki/Nominal_type_system), where the _name_ (or [fully qualified class name, FQCN](https://en.wikipedia.org/wiki/Fully_qualified_name)) of an object determines whether or not it is equal to another object, or assignable to a variable of a particular type. [For example, in Java](https://www.mycompiler.io/view/BDKXhWg)

```java
class Dog {
  public String name;
  public Dog (String name) {
    this.name = name;
  }
}

class Person {
  public String name;
  public Person (String name) {
    this.name = name;
  }
}
```

If you create a `Dog` and a `Person` with the same `name`, [Java will tell you that they're not the same thing](https://www.mycompiler.io/view/JJSt7fK), even though both classes have the same _structure_ (a single `String` field named `name`) and the same internal state (`name` is `"Fido"`)

```java
Dog dog = new Dog("Fido");
Person person = new Person("Fido");

// System.out.println(dog == person); // error: incomparable types: Dog and Person
System.out.println(dog.equals(person)); // false
System.out.println(person.equals(dog)); // false
```

And [you cannot pass a `Dog` to a method which expects a `Person`](https://www.mycompiler.io/view/88L7lwy)

```java
class Greeter {
    public static void greet (Person person) {
        System.out.println("Hello, " + person.name + "!");
    }
}

// ...

Greeter.greet(person); // Hello, Fido!
// Greeter.greet(dog); // error: incompatible types: Dog cannot be converted to Person
```

## Structural Typing

In contrast, TypeScript allows for _structural typing_ in some scenarios, where the structure of the objects is all that matters (and class names are immaterial). If we had the following two classes in TypeScript, we will see -- similar to Java -- that [they are not equal when compared with `==`](https://www.typescriptlang.org/play?#code/MYGwhgzhAEAiD2BzaBvAUNaA7MBbApgFzQQAuATgJZaIbTDxZnkCuwp850AFDgcc2qIAlKjqZSAC0oQAdH3zQAvNjz4A3HQC+aHWlCQYABXzkIjMZgUCKQugyYU2HLrzU2qNUekwTpchWVVAk1MHT0HMmgAEyQgrHwAdzgkbgAiADFKWLThTUjSaAAHU3MseKToEzNGdKycvLR9RnMQfFkQVNjkJRUSmqw86AB6YegAMzAQCHwgA)

```ts
class Dog {
  name: string
  constructor (name: string) {
    this.name = name;
  }
}

class Person {
  name: string
  constructor (name: string) {
    this.name = name;
  }
}

const dog = new Dog("Fido");
const person = new Person("Fido");

console.log(dog == person); // false
```

But suppose [we write our `Greeter` class in TypeScript as](https://www.typescriptlang.org/play?#code/MYGwhgzhAEAiD2BzaBvAUNaA7MBbApgFzQQAuATgJZaIbTDxZnkCuwp850AFDgcc2qIAlKjqZSAC0oQAdH3zQAvNjz4A3HQC+aHWlCQYABXzkIjMZgUCKQugyYU2HLrzU2qNUekwTpchWVVAk1MHT0HMmgAEyQgrHwAdzgkbgAiADFKWLThTUjSaAAHU3MseKToEzNGdKycvLR9RnMQfFkQVNjkJRUSmqw86AB6YegAMzAQCHwmgyhoAHFyfHxSU0sSUjBSSmBoRBW1nkPV7YAjNuIUYKItz2Qtb3F6Fvg2jtSAAwAJfBBOgAaaAAEhQpzWYEu7QUWgAhF9GmFdE1lmdTLIIaRuP0ykNRtA-gD4MD6vA4Wg0WsMVjuN18WMiUDoGS4UA)

```ts
class Greeter {
  static greet (greetable: { name: string }) {
    console.log(`Hello, ${greetable.name}!`);
  }
}

Greeter.greet(person); // Hello, Fido!
Greeter.greet(dog); // Hello, Fido!
```

TypeScript simply checks that the object passed to `greet()` has a `name: string` field, because that's the type we specified for `greetable`: an object with a `name: string` field. It doesn't care what class `greetable` might be, [or if it has other fields and methods as well](https://www.typescriptlang.org/play?#code/MYGwhgzhAEAiD2BzaBvAUNaA7MBbApgFzQQAuATgJZaIbTDxZnkCuwp850AFDgcc2qIAlKjqZSAC0oQAdH3zQAvNjz4A3HQC+aHWlCQYABXzkIjMZgUCKQugyYU2HLrzU2qNUekwTpchWVVAk1MHT0HMmgAEyQgrHwAdzgkbgAiADFKWLThTUjSaAAHU3MseKToEzNGdKycvLR9RnMQfFkQVNjkJRUSmqw86AB6YegAMzAQCHwmgyhoAHFyfHxSU0sSUjBSSmBoRBW1nkPV7YAjNuIUYKItz2Qtb3F6Fvg2jtSAAwAJfBBOgAaaAAEhQpzWYEu7QUWgAhF9GmFdE1lmdTLIIaRuP0ykNRtA-gD4MD6vA4Wg0WsMVjuN18WMiUDoGSKfpwAsAEKUcjRTYMTrkDx2Kzue4i16OVjsTg8AWcYU0YHWcVeTZ+GSyeVcFTa0K+KSawIqBT68JzFqFc48vkmyrc3npFbRNLAtKc+AATxdjSp63ImKO2OtvIZhP+zI93rhQA)

```ts
class Bird {
  color: string
  name: string
  constructor (color: string, name: string) {
    this.color = color;
    this.name = name;
  }
}

const bird = new Bird("red", "Boyd");
Greeter.greet(bird); // Hello, Boyd!
```

## Duck Typing

In JavaScript, we might [rewrite the above TypeScript classes like](https://jsfiddle.net/y5vts2Lk/)

```js
class Dog {
  constructor (name) {
    this.name = name;
  }
}

class Person {
  constructor (name) {
    this.name = name;
  }
}

class Bird {
  constructor (color, name) {
    this.color = color;
    this.name = name;
  }
}

const dog = new Dog("Fido");
const person = new Person("Fido");
const bird = new Bird("red", "Boyd");
```

But, as JavaScript doesn't specify types using the `:` as TypeScript does, we also have to [rewrite our `Greeter` slightly](https://jsfiddle.net/y5vts2Lk/1/)

```js
class Greeter {
  static greet (greetable) {
    console.log("Hello, " + greetable.name + "!");
  }
}

Greeter.greet(person); // Hello, Fido!
Greeter.greet(dog); // Hello, Fido!
Greeter.greet(bird); // Hello, Boyd!
```

In this case, there are no type or structural constraints at all on `greetable`. JavaScript is using [duck typing](https://en.wikipedia.org/wiki/Duck_typing) here, where field and method accesses are only checked at runtime (and not at compile time, because JavaScript isn't compiled). If a `greetable` has all of the required fields, no errors will be thrown.

However, [if a field is missing...](https://jsfiddle.net/bjgz7cuo/)

```js
class Complimenter {
  static compliment (target) {
    console.log("Hello, " + target.name + "!");
    console.log("What a nice shade of " + target.color + " you are!");
  }
}

Complimenter.compliment(person); // Hello, Fido! What a nice shade of undefined you are!
Complimenter.compliment(dog); // Hello, Fido! What a nice shade of undefined you are!
Complimenter.compliment(bird); // Hello, Boyd! What a nice shade of red you are!
```

...we can get `undefined` results.

> The name "duck typing" comes from the phrase ["If it looks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck"](https://en.wikipedia.org/wiki/Duck_test). When using duck typing, we run the program as long as we can until we hit a runtime error -- until the "duck" no longer looks like a duck.

What's the Difference Between Nominal, Structural, and Duck Typing?

Rewriting My Personal Website in Next.js and TypeScript


New Year's Day is as good a time as any to roll out a new blog, I suppose.

As one of my New Year's Resolutions this year, I'm going to revamp my website, and I'm going to do it in public.

I've spent the last few weeks working with Next.js for the first time (and brushing up on my TypeScript) in order to start hosting my technical blog on my own website. (In addition to mirroring the posts [on Dev.to](https://dev.to/awwsmm), where I've been writing for a few years now.)

In addition to the ol' blog, I've also created **/project** pages for a few ongoing things I've got in the works (including this very website). The project pages synthesize groups of commits from GitHub with manual "update" log posts to give an idea as to the current status of each of my ongoing projects. I think this is a bit more dynamic than a static "portfolio" page, and it reflects a tenet of my own personal philosophy that [_un ouvrage n’est jamais achevé... mais abandonné_](https://quoteinvestigator.com/2019/03/01/abandon/).

Follow along here, [on Dev.to](https://dev.to/awwsmm), or [on Twitter](https://twitter.com/awwsmm_dot_com) for continuing updates.

Thanks for reading!

Hello, World!

Writing Git Commit Hooks in Bash, Java, and Scala


## Writing a Git Hook in Bash

[Git Hooks](https://www.atlassian.com/git/tutorials/git-hooks) can be a very useful addition to a developer's workflow.

For instance, as I'm working on [rewriting my new website using Next.js](https://www.awwsmm.com/blog/hello-world), I've set up [eslint](https://eslint.org) and have pretty strict linting rules when running Next builds.

Unfortunately, Git doesn't follow these rules by default. So it's easy to forget to run the linter, run a `git push`, and end up with a failing production build on [Vercel](https://vercel.com).

To avoid this, I've set up a simple Git Hook which runs `eslint` before every `git push`, and fails the `push` if the linter returns any `error`s:

```sh
# .git/hooks/pre-push

# pipe output (with colors) to .temp file
RESULT=$(script -q .temp npm run lint)

# if .temp file contains "error", fail
if grep --quiet error .temp; then
  printf "\n  !! Will not push -- found linting errors:\n"
  sed '1,5d' .temp | cat
  rm .temp
  exit 1
else
  rm .temp
  exit 0
fi
```

The above script runs `npm run lint`, captures the output ([with text colors](https://stackoverflow.com/a/3515296/2925434)) to a `.temp` file, and then `grep`s for `error` in that file. If it finds any instances of the word "error", it won't `push`, but will instead print the output of the `npm run lint` command:

```sh
$ git push

  !! Will not push -- found linting errors:

/Users/andrew/Git/awwsmm.com/components/CommitGroupComponent.tsx
   2:1  error  Imports should be sorted alphabetically  sort-imports
  24:4  error  Missing semicolon                        semi

✖ 2 problems (2 errors, 0 warnings)
  1 error and 0 warnings potentially fixable with the `--fix` option.

error: failed to push some refs to 'github.com:awwsmm/awwsmm.com.git'
```

This prevents useless builds on Vercel which will fail because of linting errors.

**Note:** make sure your `.git/hooks/<file>` is executable (`chmod +x .git/hooks/<file>`), or it will not prevent the particular action from occurring. It's probably best to play around with a `pre-commit` hook rather than a `pre-push` one, when testing.

## Writing a Git Hook in Java

We can do a similar thing using Java instead of bash scripting. For this example, we'll look at writing a `pre-commit` hook in Java. Instead of writing Java code to the `pre-commit` file directly, we'll add a bit of indirection.

First, create a file called `PreCommit.java` in the `.git/hooks/` directory and add some pre-commit logic to it. In this case, we're just going to fail every commit:

```java
public class PreCommit {
  public static void main (String[] args) {
    System.out.println("Java says: no committing please.");
    System.exit(1);
  }
}
```

The `System.exit(1)` gives the same result as `exit 1` in the Bash script -- the commit will fail to complete.

Next, we'll make the `.git/hooks/pre-commit` file executable with

```sh
$ chmod +x .git/hooks/pre-commit
```

...and modify its contents to read:

```sh
#!/bin/sh

# get the path to this script file
DIR=$(dirname "$0")

# Java >= 11
exec java $DIR/PreCommit.java "$@"
```

> If you're using Java 11+, you can also write this [all as a single file](https://stackoverflow.com/a/61899256/2925434), though I personally don't recommend this method as it combines Bash and Java syntax in a single file, which can be difficult for IDEs to handle in terms of syntax highlighting, etc.

With this in place, we'll now see a message like

```sh
$ git commit -m "update gitignore, more hook testing"
Java says: no committing please.
```

Note that in Java versions &lt; 11, we need to compile this script first with `javac`, so `pre-commit` should instead look something like

```sh
#!/bin/sh
DIR=$(dirname "$0")

# Java < 11
javac $DIR/PreCommit.java "$@"
exec java -classpath $DIR PreCommit
!#
```

## Writing a Git Hook in Scala

The process for [writing a Git Hook in Scala](https://alvinalexander.com/scala/scala-shell-script-example-exec-syntax/) is very similar to writing one in Java. First, define a `pre-commit.scala` file with the following contents

```scala
object Hook {
  def main (args: Array[String]): Unit = {
    System.out.println("Scala says: no committing please.");
    System.exit(1);
  }
}
```

(Note that, in Scala, the name of the class doesn't have to match the name of the file.)

Then, modify the contents of `pre-commit` to read

```sh
#!/bin/sh
DIR=$(dirname "$0")
exec scala $DIR/pre-commit.scala "$@"
!#
```

Finally, try to commit:

```sh
$ git commit -m "update gitignore, more hook testing"
Scala says: no committing please.
```

That's all there is to it.

As it takes a while for the JVM to boot up when running Git Hooks in Java or Scala, it's probably not extremely practical to do so... unless you have a lot of logic in your hook which is easier to read in Java / Scala than in a Bash script.

But anyway, it's good to know that it can be done.

Eliminate Unnecessary Builds With Git Hooks

A collection of esoteric and thought-provoking programming languages.

20 Intriguing, Unusual, and Goofy Programming Languages

A tour of the shell, from the simple and easy to the fun-but-mostly-useless.

101 Bash Commands and Tips for Beginners to Experts

Managing Your Python Project with Git and PyBuilder


## Recent Changes

There's a big gap in the commit history for this website.

On March 17, 2022, I added [a new blog post](https://github.com/awwsmm/awwsmm.com/commit/f0824e094b89dcf4acb0ec8b02ed79de72bb0eb9). You can read the post, titled ["Elegant Multi-Line Shell Strings"](https://www.awwsmm.com/blog/elegant-multi-line-shell-strings), here if you like.

Then, I made no changes for almost an entire year. I merged two dependency updates in [January 2023](https://github.com/awwsmm/awwsmm.com/commit/8c44b9d826a72051f266b0f978b23293d4928a77) and [February 2023](https://github.com/awwsmm/awwsmm.com/commit/8c7d627562ac7d476307e1bc14c2f1132db566e4). The next substantial changes I made were [on March 3, 2023](https://github.com/awwsmm/awwsmm.com/compare/8c7d627562ac7d476307e1bc14c2f1132db566e4...1a9879460df80b23a770326f3e22e5c34d9624b5), where I bumped a few dependencies and rewrote a bit of the codebase which had always bothered me / felt a bit clunky to me.

Over the past two months, though, I've been on a roll. I

- added new [`/blog` and `/projects` "home" pages](https://github.com/awwsmm/awwsmm.com/commit/6120cbd7e83fe23d7371d541b2b46ed556477799)
- [configured Dependabot](https://github.com/awwsmm/awwsmm.com/commit/77a247259be66eb2fb97bd834bf2625c66e86a7f) to keep my dependencies up to date
- [learned a bit of GraphQL](https://github.com/awwsmm/awwsmm.com/commit/f6260bbc9bd1d181fbf3f613a73008f1cfe53e4c), using it to minimize the amount of data I request from GitHub
- [wrote a new blog post](https://github.com/awwsmm/awwsmm.com/commit/d6f9309fce056d8aef741fbf7dc4e5e7f9f8c12f) about my experience trying to keep the project pages up to date

I also [organized my to-do list](https://github.com/awwsmm/awwsmm.com/commit/9818c5a61429f80fdbbfd241819e33896ad8dce7), crossing off lots of small things which had been sitting there for a while, like

- [adding my old favicon back](https://github.com/awwsmm/awwsmm.com/commit/0ab63bfb72cfcfd8f01370f5c3325690ec9a0763)
- [making code blocks less ugly](https://github.com/awwsmm/awwsmm.com/commit/f5c22e448beaf7f0fc402ee827cbe938f8f993b6)
- [linking to interactive demos](https://github.com/awwsmm/awwsmm.com/commit/932fe4bef5319e66bf63e61a7b5c24dc34e62618) on project pages

...not to mention all of the small quality-of-life development fixes I've added: restructuring the code for ease of maintenance, upgrading dependencies, clarifying docs, and just generally making my development workflow a lot easier. (I've still [got a lot to do](https://github.com/awwsmm/awwsmm.com/issues), but I'm making good progress.)

I then ported over some old blog posts from [my Dev.To](https://dev.to/awwsmm) blog to test the [new Markdown rendering and CSS](https://github.com/awwsmm/awwsmm.com/commit/8d5c08f846bda031f34031387fad807f10b9c5d6) I added, and to have some data for [Vercel analytics](https://github.com/awwsmm/awwsmm.com/commit/f599298058d9d13fd8255e108b90ca277ea56dcd). These are some of the posts I'm most proud of, including

- ["20 Intriguing, Unusual, and Goofy Programming Languages"](https://www.awwsmm.com/blog/20-intriguing-unusual-and-goofy-programming-languages)
- ["Managing Your Python Project with Git and PyBuilder"](https://www.awwsmm.com/blog/managing-your-python-project-with-git-and-pybuilder), and
- ["101 Bash Commands and Tips for Beginners to Experts"](https://www.awwsmm.com/blog/101-bash-commands-and-tips-for-beginners-to-experts)

Finally, I also added [social buttons](https://github.com/awwsmm/awwsmm.com/commit/540cefdd7bf136ca91c9ab01b3b832d88dfb05b3) to the bottom of blog posts to make them easier to share, and set log entries on project pages to [collapse when they're at the bottom of the project update history](https://github.com/awwsmm/awwsmm.com/commit/e95822a7342eacaf62683d1066e271af5e5d768b), because I've now got too many commits and my last log entry for awwsmm.com is all the way at the bottom of the page -- the victim of my own productivity.

## Roadblocks

March 2022 to March 2023 was a busy time for me. I left my job, moved out of Ireland, got married, went on a two-month honeymoon road trip around the U.S., moved to Canada, started a new job, and survived my first Canadian winter. It's only now that I'm really starting to recover from all of that, and starting to have a good chunk of time to work on my website again.

But that being said, before all of those big life changes happened, I had set the bar very high for myself to keep this website up to date. It was definitely over-engineered. Cleaning up the confusing stuff, removing roadblocks, and making the path to developing and writing straighter and smoother have led to a huge number of improvements over the past few months.

I hope to keep that momentum going with more log entries, blog posts, and project updates in the coming months. Stay tuned!

Incremental Progress, No Matter How Slow, Is Better Than No Progress At All

Slow and Steady Wins The Race


Boy have I learned a lot over the past few days.

As you can see from [the recent round of commits I've made](https://github.com/awwsmm/awwsmm.com/commits/master), I have been working on a few things...

### Requiring `Commit`s to have a defined `date`

[This commit](https://github.com/awwsmm/awwsmm.com/commit/2b7c742d264a5571efb76c10b88fe8cc71d742e1) moves from a `Commit` with a `date: string | undefined` field to one with a `date: string` field.

Originally, I tried to make my model class (`Commit`) match the GitHub API as closely as possible, and since [`GET /repos/{owner}/{repo}/commits`](https://docs.github.com/en/rest/reference/commits#list-commits) can return commit objects with possibly `null` `author`s as well as `committer`s, it's possible for a commit returned from the GitHub API to not have a date at all.

That... seems unlikely, so I now assume that all commits will indeed have dates, and throw an `Error` in the `Commit` `constructor` if `date` is `undefined`. This can be tested during development, and (combined with the next change) means that I've removed all explicit `undefined` types from the current codebase.

### Require `CommitGroup`s to have at least one `Commit`

[This commit](https://github.com/awwsmm/awwsmm.com/commit/cb8eb7b1b2c902a4d66cd454152e3dc3641fb4ff) changes a lot of things. Firstly, it requires that `CommitGroup`s have at least one `Commit` in them. It does this by throwing an `Error` from the `constructor` if an attempt is made to create a `CommitGroup` with an empty array of `Commit`s.

This is really helpful because if a `CommitGroup` must have at least one `Commit` and (from the last update) if a `Commit` must have a definite `date`, then `CommitGroup`s can have definite `start()` and `end()` timestamps. This means that `start()` and `end()` can have type `Date` rather than `Date | undefined`. That change removes the last explicit `undefined` types from the codebase. This means we shouldn't have to do much more "`?.`" / "`??`" checking.

### Ease serialisation by moving from methods to fields

The reason I haven't updated this project in a few days is because I tried to do too much all at once (I fall into that rabbit hole sometimes). One of the things I was trying to do was to return `class`es (rather than plain objects) from the `getStaticProps` methods in my dynamic route definition files (`/pages/blog/[slug].md` and `/pages/projects/[id].md`).

I ran into some issues here (specifically around defining custom `toJSON()` methods) and everything went a bit haywire so I've backed that out of this group of commits for now.

Anyway, the point is: serialisation is confusing enough as-is without including a bunch of methods and custom `class`es. So I'm trying to store as much data in object fields, rather than in methods which calculate some value. To that end, I moved all of the methods in `ProjectUpdate` to fields in these updates, which means that `LogEntry` and `CommitGroup` also have these as fields now instead of methods (`start` instead of `start()` for example).

This made it easier to make the next change, as well.

### Make `CommitGroup` class immutable

As `start` and `end` are now fields of `CommitGroup` rather than methods, and as `Commit`s are themselves immutable (containing only `readonly` fields), it made sense to try to make `CommitGroup`s immutable as well.

> In general, immutability of objects is something worth working toward. It makes the state of an object easier to reason about and can eliminate race conditions in multithreaded environments (so, not JavaScript, really). However, immutability can make your program less performant, as you have to create an entirely new object whenever you want to update a field.

This was easy enough -- just making the array of `commits` `readonly`, and making `add()` return a new `CommitGroup` rather than mutating the current one makes the class effectively immutable. We just need to remember to save the result of `add()` to a new variable when updating a `CommitGroup`.

### Try not to hit the GitHub rate limit

Finally, I made one small band-aid kind of change, where I don't query GitHub for commits when in development mode. This is easy enough to check in Next.js

```js
if (process.env.NODE_ENV === "development") {
  // do development stuff
} else {
  // do other stuff
}
```

so I simply return an empty array of `Commit`s when in development mode. A better solution here would be to

- query GitHub for commits
- save those commits to a temporary cache file
- don't query a second time if a cache file is present
- delete the cache file on a `git push`

This would give a better idea of what the site will look like when it goes live, but it's a bit more involved, so I'll do that later. For now, I just return an empty array.

### Potpourri

Finally, in [this commit](https://github.com/awwsmm/awwsmm.com/commit/e31fdc8274f2e131fd3f8b0ec508f90930b3144d) I did some refactoring, moving some classes around in a way that seemed to be a bit more organised.

And in the last few commits this round, I hit a bug where I was trying to use `String.replaceAll`, but I was targeting an older ES version which doesn't support that method.

So, all in all, lots done here, but lots more to do.

Blog

Projects