Specifications Should Publish Changelogs

[Julian]

Proposal

A new specification should come with a list of highlighted changes over previous specifications.

This eases the burden both for spec implementers but also for users porting over old schemas.

The website should then likely link to this changelog.

In Python-land, I've found something like https://pypi.python.org/pypi/towncrier to be useful for this purpose, such that as we make individual changes to a spec, they should come with fragments that can be collected together later into the changelog. git logs are typically too noisy, and lack information about large-ness of changes, but we might want to look into something similar that is git-native.

(Apologies if we've already done this and I'm not finding it in my <30 seconds of looking).

[handrews]

I already did that- it's on the wiki and @adamvoss opened a PR for the web site json-schema-org/json-schema-org.github.io#127

which I haven't done anything about b/c I've been sick for the past week and dealing with other things and am quite frankly feeling a bit overwhelmed- not that there's so much JSON Schema stuff but that it's on top of too many other things right now. I still haven't even found that $ref/$id python code that I really want to show you for possible use.

[adamvoss]

While not nearly as detailed as the document prepared by @handrews, there is also a changelog built in to the spec as an appendix. The specification links page links to it (see Changes:), but perhaps that link is too buried.

---

@handrews I'm not sure how to wish you well and luck on getting back on top of things, with out risking it sounding self serving or passive aggressive since I have open PRs (on which there is no rush, btw). But it sucks to be sick and overwhelmed and I hope you get feeling better soon.

[Julian]

A ha! That FAQ definitely looks like it's in the right direction. @adamvoss nice work.

@handrews definitely understood, best of luck here too.

Will close this out and keep an eye on the PR.