Skip to content

index.md

Latest commit

 

History

History
89 lines (61 loc) · 2.31 KB

index.md

File metadata and controls

89 lines (61 loc) · 2.31 KB
title SPEC 10 — Changelog
number 10
date 2024-06-03
author
Inessa Pawson <inessapawson@gmail.com>
discussion https://discuss.scientific-python.org/t/
endorsed-by

Description

SPEC 10 provides guidelines and best practices for maintaining a changelog file for libraries in the Scientific Python ecosystem.

Core Project Endorsement

Ecosystem Adoption

The endorsement of this SPEC signifies your project's support for the guidelines laid out in the document.

Implementation

Keeping a clear, organized, and human-readable record of notable changes for each version of a Python library is essential for the project’s maintenance and sustainability. It promotes transparency and trust between the project’s leadership team, developers, and users.

What Is a Changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Guiding Principles

  • Changelogs are meant for humans, not machines.
  • Every version should have an entry.
  • Group similar types of changes together.
  • Make versions and sections linkable.
  • List the most recent version first.
  • Display the release date for each version.
  • Indicate if you follow Semantic Versioning.

Types of Changes

  • Added: New features.
  • Changed: Modifications in existing functionality.
  • Deprecated: Soon-to-be-removed features.
  • Removed: Features that are now removed.
  • Fixed: Bug fixes.
  • Security: Vulnerability fixes.

Standard Changelog Format

There is not one standard changelog format.

ADD EXAMPLES

Naming the Changelog File

CHANGELOG, HISTORY, NEWS, or RELEASES are widely accepted names for changelog files.

GitHub Releases

TO DO

Automation

TO DO

Editing a Changelog

It is generally acceptable to edit a changelog for the following reasons:

  • maintaining accuracy of the records about the changes in each release (e.g., adding essential information that was left out when the initial changelog was published)
  • improving clarity and readability of the change log. Try to avoid nitpicking when making edits to the changelog.

Notes