Changelog

From NovaOrdis Knowledge Base
Revision as of 02:21, 11 April 2021 by Ovidiu (talk | contribs) (→‎Example)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

External

Internal

Overview

A CHANGELOG is a text file that contains a curated, synthetic and chronologically ordered list of notable changes for each version of the project. This is useful because it is easier to describe notable changes in this format instead of asking the users to parse Git logs. In the words of https://keepachangelog.com/, "Who needs a changelog? People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how."

Guiding Principles

  • There should be an entry for every single version.
  • The same type fo changes should be grouped together:
    • "Added" new features
    • "Changed" to existing functionality
    • "Deprecated" soon-to-be-removed features
    • "Removed" previously deprecated features
    • "Fixed" bug fixes
    • "Security" in case of vulnerabilities)
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.

Naming

CHANGELOG.md is preferred.

Example

# CHANGELOG
## [0.1.0] - 2021-04-10
### Added
- something
- something else
### Changed
- something
- something else
### Deprecated
- something
- something else
### Removed
- something
- something else
### Fixed
- something
- something else
### Security
- something
- something else