Skip to content

A release check, with the config diff built in

A short checklist plus a diff of the config that changes between environments.

The code was reviewed and the tests passed, and the release still broke, because production reads a setting that staging does not have. A flag that was on in one environment, a URL that still points at the old service, a certificate date that expired last week. Release problems are very often not code problems. They are differences between two files that nobody compared.

This template is a release checklist whose middle is that comparison. The plain tasks are the ones every release has: the version, the changelog, a smoke test, the tag. The action tasks are the ones that catch the quiet failures: a diff of the configuration between environments, a validation of every JSON file that changed, and a check of every date or expiry time in the files.

Use it for a mobile release, a web deploy or a library publish. If your release has steps of its own, add them as tasks, so this is the one place the whole list lives and the one you open next time.

Use it now

6 tasks, in the order you do them. Tasks with a tool open it with the job's files and tick themselves when you save the result.

  1. 1Bump the version and update the changelog
  2. 2Diff production config against stagingCompare Text
  3. 3Validate the changed JSON filesJSON Formatter
  4. 4Check the dates and expiry times in the configTimestamp Converter
  5. 5Run the smoke test on the build
  6. 6Tag the release
Makes this job on your desk, on this device. No account.

Step by step, and why the defaults are what they are

1. Diff production config against staging

Paste the production config on one side and staging on the other in Compare Text, with Ignore whitespace on. Read every changed line, and for each one write in the note whether the difference is intended.

Why this default. Some differences are meant to exist, such as hostnames and keys. The ones you cannot explain are the ones that fail. Writing "intended" or "why?" next to each line forces the decision to be made on purpose, not by skimming a diff. Open Compare Text.

2. Validate the changed JSON files

Paste each JSON file that changed into JSON Formatter. If it formats, it parses. Turn on Sort keys if you also want to compare it with the previous version without noise.

Why this default. A trailing comma in a config is one of the most common ways a release fails on startup, and it is invisible in a diff. A validation takes a few seconds and tells you exactly where the problem is. Open JSON Formatter.

3. Check the dates and expiry times

Paste any Unix timestamps from the config, tokens or certificates into Timestamp Converter and read them as dates. Make sure nothing expires before the next release.

Why this default. A number such as 1767225600 means nothing to a person, and an expiry that has passed or is next week is exactly the thing that causes an outage on a Saturday. Seeing it as a date is what makes people notice. Open Timestamp Converter.

Variants

A mobile release

Add tasks for the store listing text, the build number and the review notes, and compare the release configuration of both platforms.

A library release

Add tasks for the public API changes and the deprecation notes, and diff the package manifest against the last release.

A hotfix

Keep only the diff and the smoke test. A short checklist that is actually followed is better than a long one that is skipped.

Common problems

The diff is too long to read.

Sort the keys in both files first and ignore whitespace. If it is still long, compare section by section instead of the whole file.

The two environments legitimately differ a lot.

Keep a note of the expected differences and compare only the keys that should match. The list of what should differ is useful on its own.

A timestamp is in milliseconds.

Timestamps with 13 digits are milliseconds, and 10 digits are seconds. The converter lets you choose.

Questions

Should I paste production secrets here?

Do not. Replace secret values with a placeholder before comparing, since the point is the structure and not the secret itself. The tools run locally, but secrets do not belong in any scratch space.

Can this replace a CI pipeline?

No. It is a checklist for a person, for the checks that are easier to see than to automate.

Where do I keep the history of past releases?

Mark the job done and keep it in the Done column. It stays in your browser until you delete it, so export a backup if you want the history to last.

More in the Developer kit

  • Daily scratchpad – Colours, JSON, diffs and regexes in one place, with the useful ones kept in a note.
  • Bug report – Steps, log, config diff and a small screenshot, ready to paste into the tracker.
  • JSON to CSV for a sheet – Turn an API response into rows someone can open in a spreadsheet.

About the Developer kit · How TabShed works