docs icon indicating copy to clipboard operation
docs copied to clipboard
verified publisher icon docker

Create a standardized changelog format

Open sarahsanders-docker opened this issue 8 months ago • 2 comments

Is this a docs issue?

  • [x] 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

sarahsanders-docker avatar May 01 '25 20:05 sarahsanders-docker

@sarahsanders-docker Can I claim this one?

ricklarsen avatar May 04 '25 17:05 ricklarsen

initial thoughts:

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

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.

ricklarsen avatar May 04 '25 18:05 ricklarsen