Move to JSON as the metadata format for DiffX.

Review Request #11702 — Created July 5, 2021 and submitted

Information

DiffX
master

Reviewers

Initially, DiffX was envisioned as having a YAML-style metadata format.
This was an attempt to keep the appearance of metadata similar to that
of several diff variants, such as Git-style diffs. However, none of
these variants had any sort of grammar defined for their format. They
were just entirely ad-hoc.

We couldn't depend on YAML itself, due to numerous parser
inconsistencies. A home-grown grammar was defined, but this would be yet
another custom structured data format, and this seemed to be the wrong
place to introduce this.

Instead, we're now using JSON as the metadata format. This has a couple
significant advantages:

  1. JSON is widely available in nearly any language, and through command
    line tools, making it very easy to support.

  2. No part of JSON output should conflict with the syntax of DiffX,
    unified diffs, or any known custom diff format.

This change updates the spec to make it clear that JSON is the official
format used for DiffX, and to update all the example diffs and metadata
to use it.

Built the docs. Checked all the example diffs and metadata examples to
ensure they had correct syntax and was rendering correctly.

Summary ID
Move to JSON as the metadata format for DiffX.
Initially, DiffX was envisioned as having a YAML-style metadata format. This was an attempt to keep the appearance of metadata similar to that of several diff variants, such as Git-style diffs. However, none of these variants had any sort of grammar defined for their format. They were just entirely ad-hoc. We couldn't depend on YAML itself, due to numerous parser inconsistencies. A home-grown grammar was defined, but this would be yet another custom structured data format, and this seemed to be the wrong place to introduce this. Instead, we're now using JSON as the metadata format. This has a couple significant advantages: 1. JSON is widely available in nearly any language, and through command line tools, making it very easy to support. 2. No part of JSON output should conflict with the syntax of DiffX, unified diffs, or any known custom diff format. This change updates the spec to make it clear that JSON is the official format used for DiffX, and to update all the example diffs and metadata to use it.
a936062472b27c83d13722c817abfe34c39d8fab
Description From Last Updated

Maybe put "json" first in the list? We should probably also highly recommend that this option is included, even though …

daviddavid

F401 'pygments.token.Punctuation' imported but unused

reviewbotreviewbot

F401 'pygments.token.Operator' imported but unused

reviewbotreviewbot

F401 'pygments.token.String' imported but unused

reviewbotreviewbot
Checks run (1 failed, 1 succeeded)
flake8 failed.
JSHint passed.

flake8

david
  1. 
      
  2. docs/spec/section-format.rst (Diff revision 1)
     
     
     
    Show all issues

    Maybe put "json" first in the list?

    We should probably also highly recommend that this option is included, even though there's only the one format for now.

    1. Gonna make me redo all the examples and length calculations? ;)

      Maybe worth doing. I'm also okay with it just being the default if nothing is specified, and calling that out specifically here.

    2. Thinking about:

      1. Ditching the format list and just specifying json as a valid option.
      2. Specifying that it's optional, and if ignored, json is implied.
      3. Recommending all diff parsers to explicitly check this and, for now, ensure that it's either json or blank, in order to avoid breaking if dealing with a future spec'd version of a file.

      I think that would prevent the biggest issue (bad assumptions by diff parsers), but I don't know. I can include it in all of our examples just in case. What do you think? Are there advantages to recommending it be explicit?

    3. Scratch that last part. I'll make it a recommendation and clear up the requirements for diff generators and parsers.

  3. 
      
chipx86
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to master (401df9f)