armor: Prevent serialization backwards compatibility problems using golden tests

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Tests the serialization backwards compatibility of data types by storing serialized representations in .test files to be checked into your project's version control.

[Skip to Readme]


Versions 0.1, 0.2, 0.2,
Change log
Dependencies base (>=4.6 && <4.16), bytestring (>=0.10 && <0.12), containers (>=0.5 && <0.7), directory (>=1.2 && <1.4), filepath (>=1.4 && <1.5), hashable (>=1.3 && <1.4), HUnit (>=1.5 && <1.7), lens (>=4.16 && <5.1) [details]
License BSD-3-Clause
Copyright Doug Beardsley, Formation Inc.
Author Doug Beardsley
Category Data, Testing
Home page
Bug tracker
Source repo head: git clone
Uploaded by DougBeardsley at 2021-05-06T21:03:08Z


[Index] [Quick Jump]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for armor-0.2

[back to package description]


Build Status

Armor yourself against backwards-incompatible serializations once and for all.

See the ChangeLog for information about changes between versions.


As almost everyone with significant experience managing production software systems knows, backwards compatibility is incredibly important for any data that is persisted by an application. If you make a change to a data structure that is not backwards compatible with the existing serialized formats, your app will break as soon as it encounters the existing format. Even if you have 100% test coverage, your tests still might not catch this problem because it's not a problem with your app at any single point in time, but a problem with how your app evolves over time.

More subtly, if you deploy a backwards incompatible migration, your app may persist some data in the new format before it crashes on the old format. This can leave your system in the horrible state where not only will it not work with the new code, but rolling back to the old code will also break because the old code doesn't support the new serialized format! You have two incomptable serializations active at the same time!

Proper migration systems can reduce the chances of this problem occurring, but if your system has any kind of queueing system or message bus, your migrations might not be applied to in-flight messages. Clearly we need something to help us protect against this problem. Enter armor.

For an overview of how to use this package, check out the literate Haskell tutorial in the test suite.


Inspiration for this package came from Soostone's safecopy-hunit package.

Details were refined in production at Formation (previously Takt).