DEV Community: Kevin Jalbert

Keep a macOS Application Running using cron

Kevin Jalbert — Fri, 28 May 2021 00:00:00 +0000

I have used RescueTime (Referral Link) for many years at this point. It always disappoints me when I get the email saying that no data was recorded in RescueTime for the last week (see image above article title). For reasons unannounced to me, the macOS menu bar application had stopped running. I use the Bartender for macOS to hide certain menu bar applications (as they offer little visual value) – RescueTime is hidden from my view and I never noticed it wasn’t running.

I needed a way to ensure that the application was kept running if it crashed.

Launch Application in Background using `cron`

I know of cron and how it can run scripts periodically – I figured this would be the tool to save me here.

I quickly put together the following (add this using crontab -e):

*/5 * * * * open --hide --background /Applications/RescueTime.app

Using crontab.guru we can see that this will run the open for ResuceTime command every 5 minutes. The --hide and --background ensure that the application doesn’t open in an obtrusive manner (i.e., think applications with a GUI).

This worked for me – it opened RescueTime if it was closed out. I even tested this with other applications and it mostly worked as expected. The hide and background flags didn’t work for some applications (e.g., Evernote always appears in the forefront for whatever reason).

Done deal then right? Wrong. I noticed every now and then a keystroke or two wouldn’t register. When I looked at the time it was always on the minute the cron would trigger… If I had to take a guess, the open was causing focus to switch briefly and would interrupt keystrokes on the current application I was in.

I could decrease the frequency that the command would run or…

Only `open` if Application isn’t Running

My next approach was to only open the application if it wasn’t already running. This will prevent the open from triggering multiple times during the day.

# Scroll to see full command (it is one line due to fitting in the crontab)
*/5 * * * * app=Rescuetime; ps aux | grep -v grep | grep -ci $app > /dev/null || open --hide --background /Applications/$app.app

If we break this down:

app=Rescuetime; sets a variable of what application we’re trying to keep open.
ps aux | grep -v grep | grep -ci $app > /dev/null lists all running processes, excluding the grep process, and finally counting the found lines while greping for the application’s name. This ends up being a 0 or 1. The STDOUT output is directed to the void so that it doesn’t create new mail entries.
|| will conditionally run the next statement if the previous was falsey (i.e., no application was found running)
open --hide --background /Applications/$app.app opens the specified application

Now this works as expected! I no longer have to worry about RescueTime not running. I might do this for other menubar applications that I like to have active, but are hidden.

I haven’t tried this on Linux but I suspect you could do something similar (assuming there is an equivalent to open).

AppleScript that Mirrors iPhone to QuickTime

Kevin Jalbert — Fri, 30 Apr 2021 00:00:00 +0000

Like many, I’m guilty of playing mobile games on my iPhone. For the games that have controller support, I’ll stream the video on a larger screen. As mentioned in my previous article, I’ll sometimes play on my exercise bike. In this situation, I’ll mirror my iOS device through QuickTime so that I can play on a larger screen with a controller.

Manual Steps

There are a number of steps that I have to complete to mirror my iPhone to QuickTime:

Enable KeepingYouAwake (so monitor doesn’t go to sleep with no inputs)
Open QuickTime
Make a new Movie Recording
Select my iPhone for video input
Select my iPhone for audio input
Drag the volume slider to 100%.
Maximize Quicktime window

Sweet Automation

This GIF demonstrates the automation that covers all seven manual steps. I launch it using Alfred.

The Code

I may be biased, but the source code is organized quite well in my opinion. The first eight lines cover all necessary customization needs as they are just function calls. If you need to, you can always dive into the functions themselves. The following is the code hosted on a Public Gist.

Challenges

Selecting a video input

I had to select my iPhone for the video/audio inputs in QuickTime using AppleScript. A quick search turned up this Stack Overflow question. It turns out that you should be able to do the following:

tell application "QuickTime Player"
    set newMovieRecording to new movie recording
    tell newMovieRecording
        set current camera of newMovieRecording to "Kevin's iPhone"
        set current microphone of newMovieRecording to "Kevin's iPhone"
    end tell
end tell

Unfortunately, it doesn’t work as you get hit with Can’t make "Kevin's iPhone" into type video recording device. This would have made things much easier.

Instead, we have to click the button to open the inputs list and then make the selections via AppleScript. This wasn’t too bad initially, as it was just iterating the list of menu items and clicking the one which matched my device’s name.

Same name for audio/video inputs

After I was able to select the video input, the next problem is selecting the audio input. The problem now is that the audio and video input share the same name and are within the same list. I would have to skip the first one (video input) to select the audio input. This wasn’t too hard but was just another hurdle to get over. Ideally, the list of inputs would have been separated by video/audio, or somehow have a different key to reference them by.

Inputs menu was slow to close

I had noticed earlier that when the inputs menu was opened it would stay open for 7-8 seconds before making the menu item selection. I wasn’t too concerned at the time, but after the whole automation was done it took just under 20 seconds to mirror my device.

It took a lot of digging but I found a Stack Overflow answer that provided the solution.

on openInputMenu()
    ignoring application responses
        tell application "System Events" to tell process "QuickTime Player"
            click button 2 of window 1
            delay 1
        end tell
    end ignoring
    do shell script "killall 'System Events'"
end openDeviceMenu

This function for opening the menu is explicitly telling it to ignore the application responses (i.e., don’t wait for feedback). A manual delay of a second is injected to give time for the menu to open up. It also kills the System Events, which ends up forcing the script to continue execution to future actions. I’ll be honest, I’m not 100% on the specifics but it worked – the menu opens and the selections are made in just over a second now.

iTerm2 Mouseless Copy

Kevin Jalbert — Sun, 06 May 2018 23:53:20 +0000

Cover image 3D printed mouse by Creative Tools is licensed under CC BY

Where possible, I try to avoid using the mouse. I heavily use Vim while editing which allows for keyboard navigation. I have taken such a liking to the Vim keyboard-bindings that I even use Vimium (a Google Chrome extension) for keyboard-driven navigation in my browser (for as much as I can). In addition, I use BetterSnapTool for MacOS, which allows me to move/resize windows around solely from my keyboard.

One optimization within my terminal that I have been avoiding is tmux – it is unnecessarily complicated for what I need. For the most part, I am able to use iTerm2 to open tabs, split panes and navigate around. To be honest, I don’t really need the session keeping functionality that tmux or screen provided. The big gain I was missing from tmux was the famed copy mode.

A quick snippet from iTerm2’s documentation of highlights for text selection:

You can use the mouse.

You can use the find feature’s “mouseless copy” feature.

You can use Copy Mode.

The first one we’re not interested in as it’s the standard way to select and copy text. We will cover others two in the sections that follow.

Find and Copy

So one approach to copying anything within the iTerm2’s session is to use the default search. It is an interesting approach, to say the least:

Essentially, you initiate the search with cmd+f and you can use the enter and tab to move your selection around and to control how much of the text you want in your selection. It works in a pinch, but if you mess up the amount of text in your selection, you basically have to restart the process. In addition, I found the shift+tab command cycled the selected search result, leading to some confusion.

To be honest, I don’t use this search copying approach very often. I find it difficult to get right, as you cannot really afford any mistakes. The following is a summary of this approach:

Searching for some text using cmd+f.
Use enter to move to the next search result.
Use shift+enter to move to the previous search result.
Navigate until you are on the desired location.
Use tab to expand your search to the next word.
Use shift+tab to expand your search to the previous word.
- Although it moves to the previous search result if one exists.
When your search term is selected, use cmd+c to copy the selection.
Use esc to exit search, and now you have the selection in your clipboard.

Copy Mode

This iTerm2 mode attempts to emulate as much of the tmux copy mode as possible, allowing you to make text selections using the keyboard. It is a mode very much like Vim’s insert and normal modes. It is important to note that the session within the pane will stop updating when you enter copy mode.

I highly recommend reading the documentation on iTerm2’s copy mode as it completely covers the keyboard shortcuts and features. Copy mode, in my opinion, is the superior of the two approaches for mouseless copying. I highly recommend giving it a shot the next time you reach for your mouse. The following is a quick summary of copy mode:

Enter copy mode with cmd+shift+c.
Basic Vim keybinding, many keystrokes can active different actions.
- v to select by character.
- shift+v to select by line.
- ctrl+v for rectangular selection.
- ctrl+space to stop selecting.
- y to yank/copy the selection (also exits copy mode).
- q to exit copy mode.
Can chain off of iTerm2’s search feature.

Jest Snapshots: Reducing styled-jsx Noise

Kevin Jalbert — Wed, 11 Apr 2018 23:53:20 +0000

Cover image Total Eclipse Light by howardignatius is licensed under CC BY-NC-ND

Facebook’s Jest is a powerful testing framework for JavaScript. It works out of the box for React projects and is essentially the de facto testing framework for React. When I began using Jest in combination with React I fell in love with the snapshot testing functionality. Having snapshots helps detect structural regressions in the rendered DOM, as per the homepage’s documentation:

Capture snapshots of React trees or other serializable values to simplify testing and to analyze how state changes over time.

During my work with React and Jest, I was using styled-jsx as my CSS-in-JS technology choice. Many times, I saw the following when I made any CSS changes:

FAIL src/App.test.js
● renders without crashing

  expect(value).toMatchSnapshot()

  Received value does not match stored snapshot 1.

  - Snapshot
  1. Received

  @@ -1,28 +1,23 @@
   <div
  - className="jsx-188895008 App"
  + className="jsx-3481390381 App"
   >

This is because the CSS changed for this scoped component and thus the jsx-######## (unique id) reflects the change.

To me, these changes in the snapshot diffs are noise and it is harder to see the structural DOM changes. The original className for the DOM elements are still present, and ideally, I would just want snapshots without any of the styled-jsx stuff present.

We will first start with a simplified App component using create-react-app as the base. The goal is to illustrate the project setup, what the snapshots look like, how to reduce the noise, and what the snapshots look like afterwards. styled-jsx provides a way to style your components using inline styles or external CSS files, so we will consider both in this article. In addition, we will also consider both the react-test-renderer and enzyme Jest snapshot rendering methods.

Given the above information, the following sections will cover these scenarios:

Inline styles with react-test-renderer
Inline styles with enzyme
External styles with react-test-renderer
External styles with enzyme

Inline Styles

import React, { Component } from 'react';

class App extends Component {
  render() {
    return (
      <div className="App">
        <p>
          Example Component
        </p>
        <style jsx>{`
          .App {
            text-align: center;
          }
        `}</style>
      </div>
    );
  }
}

export default App;

To make this all work, you have to add the styled-jsx/babel to plugins in the babel configuration.

"babel": {
  "presets": [
    "react-app"
  ],
  "plugins": [
    "styled-jsx/babel"
  ]
}

Snapshots with react-test-renderer

Within the context of inline styles, we’ll first look at the default approach for testing with Jest snapshots using react-test-renderer.

import React from 'react';
import ReactDOM from 'react-dom';
import renderer from 'react-test-renderer';

import App from './App';

it('renders without crashing', () => {
  const tree = renderer.create(<App />).toJSON();
  expect(tree).toMatchSnapshot();
});

This generates the following snapshot:

exports[`renders without crashing 1`] = `
<div
  className="jsx-188096426 App"
>
  <p
    className="jsx-188096426"
  >
    Example Component
  </p>
</div>
`;

If we change one aspect of the CSS (i.e., the text-align value), we get the following snapshot diff:

- Snapshot
+ Received

 <div
- className="jsx-188096426 App"
+ className="jsx-1500233327 App"
 >
   <p
- className="jsx-188096426"
+ className="jsx-1500233327"
   >
     Example Component
   </p>
 </div>

We can see the jsx-######## noise in our diff. One other thing to note here is that the p element also has the noise even though our CSS doesn’t target it!

To eliminate this noise, let us remove the styled-jsx/babel plugin from the test environment (you will want to specify your different environments):

"babel": {
  "presets": [
    "react-app"
  ],
  "env": {
    "production": {
      "plugins": [
        "styled-jsx/babel"
      ]
    },
    "development": {
      "plugins": [
        "styled-jsx/babel"
      ]
    },
    "test": {
      "plugins": [
      ]
    }
  }
}

Now you have a snapshot that looks like this:

exports[`renders without crashing 1`] = `
<div
  className="App"
>
  <p>
    Example Component
  </p>
  <style
    jsx={true}
  >

              .App {
                text-align: center;
              }

  </style>
</div>
`;

As we can see, the jsx-######## values are no longer present, although there is now a style element which has the actual CSS. In my opinion, this is a good trade – now every element doesn’t have the ever-changing jsx-########. This alone results in cleaner snapshots from my perspective.

Snapshots with enzyme

The second approach we will look at for inline styles is snapshot testing with enzyme. This package gives you the additional functionality to assert and manipulate the component’s output. Unfortunately, the rendered component is wrapped in an enzyme specific component, which produces unnecessarily complex snapshots. Fortunately, the enzyme-to-json package provides an approach to convert the wrapped component to the standard format we’re familiar with. It is worth noting that you can further simplify the setup if you read more into the documentation of enzyme and enzyme-to-json.

import React from 'react';
import ReactDOM from 'react-dom';
import Enzyme from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';
import { shallow } from 'enzyme';
import toJson from 'enzyme-to-json';

import App from './App';

Enzyme.configure({ adapter: new Adapter() });

it('renders without crashing', () => {
  const wrapper = shallow(<App />);
  expect(toJson(wrapper)).toMatchSnapshot();
});

This generates the following snapshot:

exports[`renders without crashing 1`] = `
<div
  className="jsx-188096426 App"
>
  <p
    className="jsx-188096426"
  >
    Example Component
  </p>
  <JSXStyle
    css=".App.jsx-188096426{text-align:center;}"
    styleId="188096426"
  />
</div>
`;

Notice here that we have an additional JSXStyle element that contains the actual CSS styles. This is in addition to the original noise we have in our snapshot.

If we change one aspect of the CSS (i.e., the text-align value), we get the following snapshot readout:

- Snapshot
+ Received

 <div
- className="jsx-188096426 App"
+ className="jsx-1500233327 App"
 >
   <p
- className="jsx-188096426"
+ className="jsx-1500233327"
   >
     Example Component
   </p>
   <JSXStyle
- css=".App.jsx-188096426{text-align:center;}"
- styleId="188096426"
+ css=".App.jsx-1500233327{text-align:left;}"
+ styleId="1500233327"
   />
 </div>

If we apply the same fix as we did for inline styles with react-test-renderer (removing styled-jsx/babel plugin from the test environment), we now get the same snapshot output. Thus, there are no more jsx-######## values, however the raw CSS is within the style tag.

External Styles

I personally like to use external CSS files that I import into the components. The following shows our converted App component to use an imported CSS file instead of an inline style:

import React, { Component } from 'react';
import css from './App.css';

class App extends Component {
  render() {
    return (
      <div className="App">
        <p>
          Example Component
        </p>
        <style jsx>{css}</style>
      </div>
    );
  }
}

export default App;

import css from 'styled-jsx/css';

export default css`
  .App {
    text-align: center;
  }
`;

Snapshots with react-test-renderer

Using external CSS files has no impact on how we test the component. Thus, we can use the same test from the inline styles section. Since that is the case, let us take the same approach to eliminate the noise in the diff by removing the styled-jsx/babel plugin from the test environment.

FAIL src/App.test.js
● Test suite failed to run

  styled-jsx/css: if you are getting this error it means that your `css` tagged template literals were not transpiled.

    at Object.<anonymous>.module.exports [as default] (node_modules/styled-jsx/css.js:2:9)
    at Object.<anonymous> (src/App.css.js:3:14)
    at Object.<anonymous> (src/App.js:2:12)
    at Object.<anonymous> (src/App.test.js:5:12)

We can recover from this error, if we use a Jest manual mocks to mock out the css tagged template literal. We can accomplish this by creating the following mock under __mocks__ /styled-jsx/css.js:

function css() {
  return '';
}

module.exports = css;

Now our snapshot looks like the following:

exports[`renders without crashing 1`] = `
<div
  className="App"
>
  <p>
    Example Component
  </p>
  <style
    jsx={true}
  />
</div>
`;

We can see that the jsx-######## values are no longer present, and in addition, the style tag does not have the raw CSS. This is an improvement over the inline style approaches, as the snapshot doesn’t change with any CSS changes.

Snapshots with enzyme

We can use the same test we had when testing the inline styles using react-test-renderer. Going from what we know now, we can remove the styled-jsx/babel plugin from the test environment and mock the css tagged template literal. These two changes then result in the same snapshot that we received in the external styles using react-test-renderer.

This is a great outcome given that the use of enzyme is common in the React tests I write, and it offers the cleanest snapshots.

TL;DR

If you are using styled-jsx with Jest snapshots:
- You will see className changes for the jsx-######## values any time the CSS changes
If you are using inline styles:
- Remove the styled-jsx/babel plugin from your test environment
- See clean snapshots when using react-test-renderer
- See clean snapshots (except for raw CSS under style tag) when using enzyme
If you are using external styles:
- Remove the styled-jsx/babel plugin from your test environment
- Mock the css tagged template literal for styled-jsx
- See clean snapshots when using react-test-renderer
- See clean snapshots when using enzyme

There might be a better way to handle this, but as of the time this article was written I have yet to see a clean approach. One thing I noticed was a GitHub comment that alluded to a better method that would follow a similar strategy to jest-styled-components but for styled-jsx.

Rails ActiveStorage Configuration for Minio

Kevin Jalbert — Mon, 26 Feb 2018 23:53:20 +0000

Cover image birdy boxcar by b.ug is licensed under CC BY-NC

You are looking at Rails 5.2 and its shiny new ActiveStorage – a built-in abstraction/mechanism to handle file storage. You decide to give it a try and remove a dependency you normally use (i.e., CarrierWave or Paperclip).

For some reason, you decide to use Minio – an Amazon S3 compatible open source project.

Looking through the ActiveStorage documentation and repository’s readme, you figure out how to get everything working locally using ActiveStorage’s local service.

Now it is time to try running everything, but with Minio as your file storage. Looking at your config/storage.yml you’ll see the template for Amazon’s S3:

amazon:
   service: S3
   access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
   secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
   region: us-east-1
   bucket: your_own_bucket

Configuration Options

Now it’s time to figure out how to use the S3 service in conjunction with your Minio server…

Region

Your Minio server doesn’t really support regions like Amazon’s S3. Just keep it as us-east-1 or your closest S3 region (although it really could be any string). From what I’ve seen, this is just used at the Amazon S3-level, and for your hosted Minio server it does not matter.

The region value is simply used to satisfy ActiveStorage and the aws-sdk-s3 gem. If you omit the region option you get the following exception missing keyword: region (ArgumentError). If you use an empty string for region you will see missing region; use :region option or export region name to ENV['AWS_REGION'] (Aws::Errors::MissingRegionError).

Endpoint

Your Minio server is hosted at some URL (i.e., https://minio123.com), so you’ll need to inform ActiveStorage’s S3 service about this endpoint. Luckily, it is just a matter of adding the URL endpoint to your configuration:

endpoint: "https://minio123.com" # Points to your Minio server

You can also use ports on the endpoint (i.e., “http://localhost:9000”).

Force Path Style

So you have the endpoint and region all setup from a configuration standpoint. Your Minio server is also up and running, along with a bucket, your_own_bucket. You try to upload a file and see the following exception:

Aws::Errors::NoSuchEndpointError (Encountered a `SocketError` while attempting to connect to:

  https://you_own_bucket.minio123.com/RJioqjrTT4VmFobw5FhXkSby

This is typically the result of an invalid `:region` option or a
poorly formatted `:endpoint` option.

* Avoid configuring the `:endpoint` option directly. Endpoints are constructed
  from the `:region`. The `:endpoint` option is reserved for connecting to
  non-standard test endpoints.

Hmm… Well that didn’t work out. If we look at the URL (https://your\_own\_bucket.minio123.com), we can see that it uses a bucket subdomain approach. However, Minio expects the bucket after the domain (i.e., https://minio123.com/your\_own\_bucket). Again, fortunately there is an configuration option we can add to force this path style:

force_path_style: true # Needed to be compliant with how Minio serves the bucket

Complete Configuration

At this point we covered all the configuration gotchas to set up ActiveStorage with Minio. Namely, the missing and (mostly undocumented) endpoint and force_path_style options. The following is a complete configuration.

minio:
   service: S3
   access_key_id: <%= Rails.application.credentials.dig(:minio, :access_key_id) %>
   secret_access_key: <%= Rails.application.credentials.dig(:minio, :secret_access_key) %>
   region: us-east-1
   bucket: your_own_bucket
   endpoint: "https://minio123.com"
   force_path_style: true

It isn’t a bad idea to have the configuration named minio, just so it is clear that it’s a Minio file storage instead of the typical Amazon S3.

Start Now: Architecture Decision Records

Kevin Jalbert — Wed, 03 Jan 2018 23:53:20 +0000

Cover image Filing cabinet by mightymightymatze is licensed under CC BY-NC

While working on any project, you’ll eventually need to make decisions regarding the task at hand. The decision that has to be made can vary in size and impact. Often we are in the context of a team, and these decisions are made in consultation with others. As time progresses, with new and old team members moving on and off the project, we’ll start to question some of those decisions that were made in the past.

Why was it done that way?

Did we not consider this alternative?

What was the context when that decision was made?

Save the team and yourself future headaches and plan accordingly for these types of questions now, by starting Architecture Decision Records (ADRs) for your project.

What are ADRs?

I first read about ADRs in the documenting architecture decisions blog post by Michael Nygard. ADRs are a form of documentation that record any architecturally significant decisions that impact a project. For an impact to be considered architecturally significant within a software project context, Micheal stated:

… those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.

Michael’s blog post was focused on ADRs within the context of an agile software project, but I believe it can be applied across different domains. The affected values for what a decision might impact would have to be altered to suit the appropriate domain. For example, altering the customer support workflow could constitute a decision record as it significantly changes a business process.

I had recently read that lightweight architecture decision records had made it into the adopt ring of Thoughtworks Technology Radar in the November 2017 edition. They note that the lightweight aspect of ADRs is to just have text/markdown files alongside software projects in their repositories.

Here is an example ADR (pretty meta as it is about starting ADRs):

# 1. Record architecture decisions

Date: 2018-01-03

## Status

Accepted

## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as described by Michael Nygard in this article: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's _adr-tools_ at https://github.com/npryce/adr-tools.

I don’t want to go into technical details of ADRs, as this blog post is to bring awareness to them, as well as tools/techniques around them. There is plenty of supplementary material in this blog post via links to other articles.

Getting Started with ADRs

The biggest thing when adopting ADRs in your project is being consistent with them. As with any added process, it’s easy to simply overlook the new parts if they aren’t at the forefront of your mind. Within our software projects, we actually incorporate ADR consideration in our GitHub pull request template. It’s a good idea to make sure all team members are all in agreement with using ADRs, as well as when to make one. You don’t want a decision to be made that is not documented.

Simplify ADRs with `adr-tools`

In addition to including a note about ADRs in our pull request template, there is more tooling to help out. In the spirit of being lightweight records, markdown files are the preferred way to write ADRs. The adr-tools command line tool is a great way to simplify the creation of ADRs. If you are on MacOS, back in May 2017, I got adr-tools accepted into homebrew, so now you can just brew install adr-tools.

There are a lot of configurations and features that exist within adr-tools. I’m going to go over some of the essentials, with examples. I highly recommend taking a deeper look into the tool itself to get the most out of it.

Initialize Repository

With a new repository, you get started with adr init, which creates the following doc/adr/0001-record-architecture-decisions.md file for you. The contents of this ADR is actually the sample one presented above.

Create New ADRs

When you want to add a new ADR, you can execute adr new "Split up component XXXX into two modules" which opens up a basic ADR template to fill in. It creates the next incremented ADR – doc/adr/0002-split-up-component-xxxx-into-two-modules.md.

Maintain Table of Contents

Most software projects have a README.md file. When working with ADRs, I include a hyperlink to /doc/adr/README.md. This file can be generated using adr generate toc > ./docs/adr/README.md, and ends up creating a nice table of contents of the current ADRs:

# Architecture Decision Records

* [1. Record architecture decisions](0001-record-architecture-decisions.md)
* [2. Split up component XXXX into two modules](0002-split-up-component-xxxx-into-two-modules.md)

Superseding Existing ADRs

Eventually, you will have a decision which is somehow linked to another ADR. A great example of this is a new ADR which supersedes an older decision. First let us make a new ADR adr new -s 2 "Combine modules back into one component", which ends up superseding our earlier decision. This will actually modify the ADR’s status section by adding the following:

# In 0002-split-up-component-xxxx-into-two-modules.md
Superseded by [3. Combine modules back into one component](0003-combine-modules-back-into-one-component.md)

# In 0003-combine-modules-back-into-one-component.md
Superseds [2. Split up component XXXX into two modules](0002-split-up-component-xxxx-into-two-modules.md)

It is useful to see how ADRs relate to each other. In our example, we’re indicating one ADR that supersedes another. It is possible to use adr link to specifically tailor the link to use different wording, so you can be specific in how ADRs are associated. Ultimately, linking provides additional context surrounding linked decisions.

Visualizing ADRs

With the ability to link ADRs together, it now becomes possible to trace the story of a specific ADR. By following links you can understand the bigger picture of how the architecture evolved over time. It can be hard to navigate one file at a time, so fortunately for us, adr-tools has us covered by being able to produce a visualization of the ADRs.

With adr generate graph | dot -Tjpg > graph.jpg we can generate the following image (using our example ADRs so far):

It is quite apparent to see the ADR links in this diagram. I personally have not seen how well this scales, although it still is a good technique to be aware of.

Using adr generate graph by itself will return a graphviz output. It would be interesting to attach this to the /doc/adr/README.md using the gravizo service. This way, the ADR visualization is always within reach and can be apart of the normal process when adding new ADRs. I have not personally done this approach, but it looks interesting.

Searching ADRs

As we’re just dealing with markdown files, it becomes trivial to search through the ADRs. The file names are the titles, so even at a glance, it becomes easy to narrow down what you are looking for. You can even use adr list to just list all the ADRs. In combination with other command line tools (i.e., grep) you can filter the list. I personally like using the fzf command line tool to filter the list and open it in vim: adr list | fzf | xargs vim.

If you want to dig deeper you can search the contents of the files for what you are looking for. For example, grep -l 'tool' ./doc/adr/*.md | fzf | xargs vim would look for any file with tool in it, and present the fzf interface for further filtering.

In the end, you can be creative on how you search through ADRs – there is a lot of flexibility built into it. I usually use the tag command line tool for searching within files.

Customizing ADRs

At this point, you might be thinking “ADRs sound great, but it doesn’t quite satisfy all my needs”. The concept of ADRs is very general and flexible in nature so that if you have specific needs or requirements, you can customize it. In our case, we’ve been using adr-tools and it has a base template. You can change it, or use a different template. For example, it might be useful to look through other templates to find one that fits your needs.

This post has been talking about using markdown files, but your ADRs could be held in any other medium (i.e., JIRA, Google Docs, etc…). I would argue to use what works best for your team. In most cases, within a software project, the markdown approach is nice as it’s very lightweight and everything is contained in the source directory.

TL;DR

ADRs are a great way keep records of architectural decisions
ADRs provide context surrounding architectural decisions
ADRs can be lightweight as markdown files that live within your project’s repository
ADRs are searchable and customizable

The best time to start ADRs is at the start of a project; the second best time is right now

DEV Community: Kevin Jalbert

Keep a macOS Application Running using cron

Launch Application in Background using cron

Only open if Application isn’t Running

AppleScript that Mirrors iPhone to QuickTime

Manual Steps

Sweet Automation

The Code

Challenges

Selecting a video input

Same name for audio/video inputs

Inputs menu was slow to close

iTerm2 Mouseless Copy

Find and Copy

Copy Mode

Jest Snapshots: Reducing styled-jsx Noise

Inline Styles

Snapshots with react-test-renderer

Snapshots with enzyme

External Styles

Snapshots with react-test-renderer

Snapshots with enzyme

TL;DR

Rails ActiveStorage Configuration for Minio

Configuration Options

Region

Endpoint

Force Path Style

Complete Configuration

Start Now: Architecture Decision Records

What are ADRs?

Getting Started with ADRs

Simplify ADRs with adr-tools

Initialize Repository

Create New ADRs

Maintain Table of Contents

Superseding Existing ADRs

Visualizing ADRs

Searching ADRs

Customizing ADRs

TL;DR

Launch Application in Background using `cron`

Only `open` if Application isn’t Running

Simplify ADRs with `adr-tools`