Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SPEC 10: Add an initial draft for a SPEC about release documentation #321

Draft
wants to merge 13 commits into
base: main
Choose a base branch
from
Draft

SPEC 10: Add an initial draft for a SPEC about release documentation #321

Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
7369c62
Add initial draft for SPEC about keeping a changelog
InessaPawson Jun 4, 2024
32c5880
[pre-commit.ci 🤖] Apply code format tools to PR
pre-commit-ci[bot] Jun 5, 2024
01c5a33
Merge branch 'main' into spec10
MSanKeys963 Sep 30, 2024
90d6396
Update spec-0010/index.md
InessaPawson Oct 4, 2024
9da9a55
Update spec-0010/index.md
InessaPawson Oct 4, 2024
0a35d21
Merge branch 'scientific-python:main' into spec10
InessaPawson Oct 4, 2024
b781266
Incorporate feedback
InessaPawson Oct 5, 2024
585ba4e
Update the Guiding Principles section
InessaPawson Oct 5, 2024
1e6f765
Update the GitHub Releases section
InessaPawson Oct 5, 2024
d3ba716
Update the Types of Changes section
InessaPawson Oct 5, 2024
82d19b1
[pre-commit.ci 🤖] Apply code format tools to PR
pre-commit-ci[bot] Oct 7, 2024
e513232
Merge branch 'scientific-python:main' into spec10
InessaPawson Oct 8, 2024
03328c9
Clarify the objectives of the SPEC
InessaPawson Oct 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions spec-0010/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
---
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

<!--
Briefly discuss what it means for a core project to endorse this SPEC.
-->

### 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.
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved
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
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved
notable changes for each version of a project.

### Guiding Principles
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved

- 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.
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved

InessaPawson marked this conversation as resolved.
Show resolved Hide resolved
### 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.
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved

### Standard Changelog Format
There is not one standard changelog format.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should at least list some that are recommended (and give reasons why they are recommended)?


ADD EXAMPLES

### Naming the Changelog File
CHANGELOG, HISTORY, NEWS, or RELEASES are widely accepted names for changelog files.
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved

### GitHub Releases

TO DO
InessaPawson marked this conversation as resolved.
Show resolved Hide resolved

### Automation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tools --- we have several to mention; sp/changelist, towncrier, scipy wiki, astropy (two mechanisms? @pllim @bsipocz?)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actions to be used by either towncrier systems or by direct edits of a single changelog file (both approaches have legitime use cases):

https://github.com/scientific-python/action-towncrier-changelog
https://github.com/scientific-python/action-check-changelogfile

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

quasi-automation: I do run cosistency checking scripts before cutting a release to ensure all PRs in a release either have a changelog, or e.g. a no-changelog-required label. So in my mind the actions are required for the PR, but in practice there is always some inconsistencies, especially when there are many people doing merges with significantly different level of tolerance towards failing CI checks.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be useful to gather info from projects which use more niche workflows (like SciPy) on what stops them from moving to an automated tool, to help guide readers. There is generic dev workflow churn, but any other reasons are probably more informative.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lucascolley Yes, there are always exemptions. Could you point me to the SciPy documentation that covers this part?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a bit of documentation at https://scipy.github.io/devdocs/dev/core-dev/index.html#release-notes. We recently also introduced a "needs-release-note" tag to try to reduce the chance that PRs are missed.


TO DO
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend adding a link to the PyPI instructions for automation here: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but this document is not about releasing, but just the changelog, and thus automation for me means e.g. the github actions checking the existence of a changelog, or the changelog framework itself, e.g. creating one single changelog file from the fragments for towncrier

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my mind, generating the changelog and the release are tightly coupled and usually happens at the same time, so for any automation to happen it would be in the same file. here is an example of an automated release pipeline generated with the above docs that also generates release notes automatically: https://github.com/duckdb/dbt-duckdb/blob/master/.github/workflows/release.yml

There is also a --notes tag that lets you add custom (generated or manually entered) notes

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like to have the changelog available, and complete/correct during the dev process already, it's quite useful for big projects, but I also find it somewhat useful to enforce the presence the changelog at the time a contribution is made


### 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.,
Copy link

@nabobalis nabobalis Jun 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We use nitpicky so any sphinx links in our changelog can often break with new releases. So that is a very common reason to edit our changelog.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does "maintaining accuracy" include fixing typo?

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Slightly related and not sure myself: should changelogs link to API like functions etc when rendered by sphinx? This can be very nice from a user perspective but over time, these references tend to get stale pretty fast due to deprecations, etc. We should probably mention this trade-off in some capacity.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, for that reason, astropy no longer put "live" links (especially intersphinx stuff) in changelog, so we don't have to go back and fix broken links N number of years later, and thus changing history (and if you type at 88mph, more bad things might also happen). Some URLs still snuck in and we handle those as need arise. Our decision had oppositions, so it is not perfect solution either.


## Notes

<!--
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another thing @InessaPawson and I chatted about is to provide a template for a GitHub profile readme that shows OSS/Scientific Python contributions:
https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@guenp After giving it more thought, I wonder if this info belongs to the SPEC about release documentation. I will keep the conversation open to gather feedack from others.

Include a bulleted list of annotated links, comments,
and other ancillary information as needed.
-->