Create a standardized changelog format

[sarahsanders-docker]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Other

Description

Review the changelogs. Suggest a standardized format (e.g., clearer versioning, flags for breaking changes).

Location

https://docs.docker.com/reference/

Suggestion

No response

[ricklarsen]

@sarahsanders-docker Can I claim this one?

[ricklarsen]

initial thoughts:

Docker Hub API Changelog

• Docker Hub API Changelog

Keep

• Changelog in title.
• Intro explains changelog.

Add

• Add one sentence description of project so readers know they found the correct changelog.
• Make version number the section headings. Include date after.
• Maybe add link to download page or documentation version for this project
• Add Subsections for new / fixed / known issues

Docker volume plugins

• Docker volume plugins

Keep

• Project overview

Add

• Move changelog to page title.
• Add subsection headers for new / fixed / known issues
• Add dates to version headings.
• Command line changes sections are not tied to the versions when they change.
  • Maybe move details and code samples to another section of documentation and link to them from here? Or move changelog to a standalone page?

---

Changelog template

Title: Project Changelog

Intro: [One sentence description of product or project.] The changelog is where to find information about new versions, including new features, bug fixes, and known issues.

Version

version release date

New features

[Omit section if no new features]

• past tense Added ...
  • link to new docs, if possible

Bug fixes

[Omit section if no new bug fixes]

• past tense Fixed ...
  • if possible link to previous Known issue later on page

Known issues

[Omit section if no open issues]

• [Situation] happens when [condition that causes issue]
  • Workaround if available.
  • link to open github issue.

Deprecated features

• [Feature] is being deprecated. Use [New feature] instead. [Add any additional information or considerations as needed]
• Include BREAKING CHANGE if removing feature could potentially break existing workflows.