Have a proper Change log

[sgpinkus]

I found something resembling a Changelog on the website FAQ via #330. But it wasn't so easy to find, looks somewhat informal, and the FAQ doesn't seem like the proper place for the change log. It should be more prominent. Also looks like you've used a different way of documenting changes in v7.

• Add Changelog file in specification repo.
• Add dedicated change log or migration page on the web site linked from the home page.
• Be clear about strategy for documenting changes and write it down in CONTRIBUTING.md.

[handrews]

The change logs are in the I-D documents. They are labeled Change Log, as in all other IETF drafts that I'm aware of.

Contributions to the web site are welcome at json-schema-spec/json-schema-org.github.io

[handrews]

To elaborate a bit- people always complain about this stuff. I keep trying to placate everyone and it doesn't work. No one else has done any work on it at all recently except move pages from place to place, and I'm out of steam. PRs welcome.

[sgpinkus]

Ok thanks for letting me know. I'll devote some time to it soon, and try to get to a PR.

[handrews]

Awesome, thanks. And yeah, I did draft-07 differently because people complained endlessly about the "FAQ" for draft-06. I am the absolute worst person to write practical documentation (that's why I write specs) but no one else has the time or inclination so I usually have to do it, which makes everyone unhappy AFAICT.

[sgpinkus]

On review this is my proposal (ticket spans the website and this repo but not going to create a duplicate on the other repo ...):

• Create a file here called CHANGES.md. Informally base format off Keepachangelog, except changes documented as a markdown table like was used on http://json-schema.org/draft-06/json-hyper-schema-migration-faq.html, because it's nice and readble.
• Remove draft-06/json-hyper-schema-migration-faq.html, and draft-06/json-schema-migration-faq.md from site. Replace with top level FAQ.md for everything, and all versions.
• Link to CHANGES.md in this repo from site wrt changes.
• Add links for FAQ and CHANGES on home pages of site.

[handrews]

@sam-at-github I'll generally be OK with things that:

• Clearly either improve clarity, or at minimum don't make it worse. This is subjective, so we may end up disagreeing. @Relequestual has the last word on web site decisions (if he has time to be involved)
• the draft-06 documents have a lot of historical stuff specific to that migration that I don't think is of long-term general interest
• I don't want a CHANGELOG here if it just duplicated the change logs that exist already. It's enough of a pain to keep it all up to date as it is.

Would you be willing to email me so we can discuss this in detail a little more easily? my email address is at the bottom of the spec.

[sgpinkus]

I don't want a CHANGELOG here if it just duplicated the change logs that exist already. It's enough of a pain to keep it all up to date as it is.

I'm always for single sourcing as a general rule. It's either here or on the site. Since you have essentially a changelog over on the site in the form of the "faq" docs I'll just start refactoring that into a change log over there. Can think about migrating the change log over here later.

I think I have enough to do a PR, but I'll use your personal email for future correspondence.

P.S. I also have a full time occupation so may not find more time for this for a bit, but will try ...

[handrews]

If you email me we can talk a bit about the backstory here, which I'm not going to dredge up in a public issue right now b/c everyone here is doing what they can and re-hashing things that can't be helped in public is lame.

[handrews]

It will likely make your PR go more smoothly.