docs: Add new in version notes

[roll]

• fixes Add "New in vX.X" notes to the specs' texts #928

[cloudflare-workers-and-pages]

Deploying datapackage with    Cloudflare Pages

Latest commit:	36f1938
Status:	✅  Deploy successful!
Preview URL:	https://2e4d568e.datapackage-6gp.pages.dev
Branch Preview URL:	https://928-add-new-in-version-notes.datapackage-6gp.pages.dev

View logs

[roll]

Hi @peterdesmet, can you please take a look?

[peterdesmet]

While useful, I think the approach with Version compatibility callouts is quite verbose. Can I suggest:

Adding the version to the header for new properties? It can be styled similar to a Bootstrap badge. It should not be appear in the header id or the table of content. This is how Jekyll documentation does it.

$schema v2.0

Or alternatively, below the title, maybe styled as small text.

$schema

New since v2.0.

[roll]

@peterdesmet
That's a nice idea regarding new properties. Let me try if I can make it work.

What would you suggest on changes like schema.missingValues (new labeled missingness)

[roll]

Another example - https://radashi.js.org/reference/array/group/

[peterdesmet]

What would you suggest on changes like schema.missingValues (new labeled missingness)

I guess we could mention the version in the text where relevant:

missingValues

...

missingValues MUST be an array where each entry is a unique string, or (since v2.0) an array where each entry is an object.

Although that's probably to hard to maintain. Alternatively, we consistently add a label to all headers where something has changed and link to the corresponding CHANGELOG section for context.

$schema New in v2.0

...

$missingValues Updated in v2.0

...