| title | SPEC 10 — Changelog | |
|---|---|---|
| number | 10 | |
| date | 2024-06-03 | |
| author |
|
|
| discussion | https://discuss.scientific-python.org/t/ | |
| endorsed-by |
SPEC 10 provides guidelines for creating and maintaining documentation related to releases for libraries in the Scientific Python ecosystem.
The endorsement of this SPEC signifies your project's support for the guidelines laid out in the document.
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.
A changelog is a file which contains a curated list of notable changes for each version of a project.
- 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 the type of release: minor, patch, pre-, ...
- Give credit to contributors. It’s a good idea to include contributions that are rarely captured by version control systems, e.g., issue and PR triage, thoughtful feedback via comments, community support work, etc.
- Automate the release process to the fullest extent while adhering to the guiding principles mentioned above.
- New features: Updates that expand/improve the existing features
- Changed: Could be further categorized as Removed, Deprecated, and Changed
- Fixed: Bug fixes and security patches, could be grouped separately
- Documentation: Updates and improvements to the library documentation
- Infrastructure: Updates related to the library infrastructure and tooling
- Maintenance: Internal updates that do not impact users directly
There is not one standard changelog format.
ADD EXAMPLES
CHANGELOG, CHANGES, HISTORY, NEWS, or RELEASES are widely accepted names for changelog files.
GitHub offers a lot of flexibility in terms of creating release documentation.
The most common approaches are:
1. Auto-Generated Release Notes:
GitHub's "Auto-Generate Release Notes" feature allows automatically generate release notes that include a list of merged pull requests, a list of contributors to the release, and a link to a full changelog (if created).
You can also customize your automated release notes, using labels to create custom categories to organize pull requests you want to include and exclude certain labels and users (e.g., bots) from appearing in the output.
This approach is adopted by ADD PROJECTS
2. Changelog-First Strategy:
Maintaining a detailed changelog file that is referenced in the GitHub release notes.
This approach is adopted by ADD PROJECTS
3. Combined Approach:
Use auto-generated GitHub release notes alongside a manually maintained changelog. This provides both details (from the automated notes) and curated insights (from the changelog). To direct users to the curated changelog for additional information, include a note (e.g., "Also see changelog for more details") on top of the generated text.
This approach is adopted by ADD PROJECTS
The selected approach often depends on a project's size, the community's needs, and the maintainers' resources and personal preferences.
For more info about releasing projects on GitHub, refer to: https://docs.github.com/en/repositories/releasing-projects-on-github
TO DO
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.