Survey of changelogs on hackage

changelogs.md

Authoritative sources

Source	Notes
Wikipedia entry	Custom format from GNU Date (YYYY-MM-DD), name, email per entry
Keep a changelog	Use markdown Emphasis on human readability Attempt at modern standard Never dump git logs there Subsections tagged by [VERSION] Top version always [UNRELEASED] Many more tips at their site

Examples from hackage

Package	Notes
lens	Markdown Entry headers usually just version number
agda	Mostly markdown Lots of prose & example code blocks Code blocks not in .md
aeson	Neither markdown nor GNU style Unformatted entry headers Changes in sections as bulletted lists
io-streams	Markdown sections with bulleted entries lately Markdown sections paragraph entries prior
text	Non-markdown section headers, bulleted list changes
wreq	Non-markdown section headers, bulleted list changes This semes to be BOS changelog style
lucid	H2 entry headers Bulleted list entries
haskell-src-exts	Markdown Pretty wordy, lots of explanation Version as X --> Y
cabal	GNU style entry headers, markdown entries Headers have date, attribution, email Changes list github issue numbers
async	No changelog
stm	<ul Markdown Version number and date in entry headers

Thoughts

• Go with compliant markdown (fairly common on hackage)
• Header titles include version and date. Names can be gotten from github.
• Break entries into subsections ADDED, CHANGED, BREAKING (not common on hackage, but useful)