Reference spec when reporting violations

[wking]

Validators (e.g. the Nu Html Checker) often report errors with references to the specification requirement that was violated. To get a good user experience and protect against checking unspecified behavior, I think ocitools checks should be setup to link to the relevant spec wording for any check they perform. For example, a bundle with non-UTF-8 JSON would fail with a reference to this. If this sounds like a reasonable policy, we should write it up in the README or a CONTRIBUTING.md and open issues/PRs for adjusting any existing checks.

[mrunalp]

@wking This is a good idea but maybe hard to maintain the links all the time. How about we target this for 1.0?

[wking]

On Mon, Jan 25, 2016 at 10:19:31AM -0800, Mrunal Patel wrote:

@wking This is a good idea but maybe hard to maintain the links all
the time. How about we target this for 1.0?

There aren't that many releases left between now and 1.0, so I'd just
start now. If we link to a particular version of the spec, it will
(a) help with stability and (b) mark stale checks that should be
audited updated after each spec release.

[wking]

On Mon, Jan 25, 2016 at 10:19:31AM -0800, Mrunal Patel wrote:

@wking This is a good idea but maybe hard to maintain the links all
the time. How about we target this for 1.0?

We're into 1.0.0-rc1, so I'd guess it's time to do this? I can start
filing PRs if we want to green-light the general idea.

[wking]

With #354 merged yesterday, we now have a way to do this. We still need to transition a lot of code to the new error model, but it's no longer blocking on designing the approach.