Digital Garden

Welcome to my digital garden! Here is where I publish anything that comes to mind which might be helpful or just entertaining to future me or maybe even you! This page is a HUGE work-in-progress right now, but each garden post I make will currenty be shown on this page. Expect a better browsing experience with links to full pages and pagination in the future as this garden grow.

ASDF Version management

I recently came across asdf. This tool is essentially a single replacement for pyenv, rbenv and nvm. It uses a plugin system to support various tools, programming languages and runtimes. It uses a .tool-versions file to determine what you need installing, but it is also capable of using your existing version files by setting the legacy_version_file option: https://asdf-vm.com/manage/configuration.html#legacy-version-file.
Recommended way to handle favicons

With so many operating systems, browsers and ways to view and link to your site, it can be confusing to know which favicon combinations to use. Andrew Sitnik has a well written article covering a recommended practise on modern favicons. Below is the code, ready to copy-paste to best use favicons in your site.

The code to include in your <head>
```
<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" href="/icon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<link rel="manifest" href="/manifest.webmanifest">
```
The code to include in your web app manifest (manifest.webmanifest):
```
{
  "icons": [
    { "src": "/icon-192.png", "type": "image/png", "sizes": "192x192" },
    { "src": "/icon-512.png", "type": "image/png", "sizes": "512x512" }
  ]
}
```
Keeping my mac organised with homebrew

I use homebrew to keep track of everything that goes on my mac. Desktop applications are handled by homebrew-cask, drivers are handled by homebrew-cask-drivers and fonts are handled by homebrew-cask-fonts. The homebrew community are pretty welcoming to new casks if you find software that isn’t included and there’s documentation for adding new casks available.

It’s inevitable that some software won’t be available outside of the mac app store though, or maybe you’ve already got a good library there. mas is the solution, allowing you to install App Store apps directly through homebrew.

To keep all this backed up, I manually run brew bundle dump occasionally to produce a Brewfile which lists everything I have installed. I then upload this to cloud storage. If I ever need to restore from a backup, I can run brew bundle from the same directory the Brewfile is in and brew will install everything again. I’ve also used Brewfiles to define dependencies for some projects!

When it comes to uninstalling, brew uninstall --cask --zap will not only remove the app, but also clean up any files leftover. This solves one of my biggest pain points with the mac.
Through the web releases and prerelease management

A number of popular open-source projects I’ve come across use fully automated releases to make both the project’s developers lives easier when deploying versions, as well as to simplify the consumer’s lives. While this might seem like a large task for smaller teams, a ‘one-click’ solution can be ready to go in less than an hour.

Tools involved
- release-it
- GitHub Actions
Getting started

Get your project setup with GitHub Actions. GitHub published a quickstart guide if you aren’t sure on how to do this: https://docs.github.com/en/actions/quickstart. We will be using the workflow_dispatch event to allow you and your team to trigger a ‘release’ workflow. We’ll also be using release-it to perform out version updating and any actions that need to be performed along with that (such as tagging or pushing to npm). For more info, see the release-it docs.

Copy and paste the following workflow code:
```
name: Release
on:
  workflow_dispatch:
    inputs:
      bump_type:
        type: choice
        required: true
        description: What kind of version bump?
        options:
          - patch
          - minor
          - major
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Git setup
        run: |
          git config user.name "${GITHUB_ACTOR}"
          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
      - name: Setup node
        uses: actions/setup-node@v3
      - name: npm install
        run: npm ci
      - name: Release
        run: npm run release -- ${{ github.event.inputs.bump_type }} --ci
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
When you view the Release workflow, this will allow you to perform a release by pressing ‘Run workflow’. A dropdown will appear asking you if you want a patch, minor or major release. The chosen option is passed through to release-it as the type of version bump to perform. The workflow also sets up the git config so that the commit is performed by whoever triggered the workflow run (using your GitHub email address).

Note that unfortunately, because this performs a git commit straight to the chosen branch, this workflow doesn’t work with GitHub’s branch protection rules. If you know of a way to get around this limitation, do reach out to me!

Automatic pre-releases

Thanks to GitHub’s great documentation on Pull Requests in GitHub Actions and a recent update to release-it, we’re able to create a ‘pre-release’ version on every successfull Pull Request merge. This is the workflow file:
```
name: Automatic pre-release
on:
  pull_request:
    types:
      - closed
jobs:
  pre-release:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Git setup
        run: |
          git config user.name "${GITHUB_ACTOR}"
          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
      - name: Setup node
        uses: actions/setup-node@v3
        run: npm ci
      - name: Release
        run: npx release-it --preRelease=next --ci --git.commitMessage="" --git.commitArgs="--amend -C HEAD"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
The main changes here are the release-it command and the workflow trigger. In order to run this on every merged PR, we need to run the workflow on every closed PR and check if the event was a successful merge. The we call release-it with preRelease-next to generate a version number that looks like this: 1.1.0-next.1. For more information on this argument, see the preRelease option documentation for release-it. Additionally, to prevent generating a messy git commit graph and release notes, we make the commit an amend so that it appears as though the version bump was done as part of the PR merge/ squash commit. While this does not now represent exactly what was done in the PR, I believe this leads to a more readable history and so is worth the trade-off. Feel free to remove the following from the release-it step if you don’t want this behaviour: --git.commitArgs="--amend -C HEAD".

Related topics

Keep A Changelog is a fantastic website for all software developers. It’s straight forward and to-the-point principles make having a readable changelog easier to write. Apply these ideas to your projects and your future self will be thanking you!

Digital Garden

ASDF Version management

Recommended way to handle favicons

Keeping my mac organised with homebrew

Through the web releases and prerelease management

Tools involved

Getting started

Automatic pre-releases

Related topics