From 7369c6267dadcea8d9061ef5424de20fabbba523 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Tue, 4 Jun 2024 13:35:01 -0700 Subject: [PATCH 01/10] Add initial draft for SPEC about keeping a changelog --- spec-0010/index.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 spec-0010/index.md diff --git a/spec-0010/index.md b/spec-0010/index.md new file mode 100644 index 00000000..d087ebc4 --- /dev/null +++ b/spec-0010/index.md @@ -0,0 +1,86 @@ +--- +title: "SPEC 10 — Changelog" +number: 10 +date: 2024-06-03 +author: + - "Inessa Pawson " +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 + + From 32c58804c27b2231cd42efef951d2f9360e58151 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 5 Jun 2024 18:11:27 +0000 Subject: [PATCH 02/10] =?UTF-8?q?[pre-commit.ci=20=F0=9F=A4=96]=20Apply=20?= =?UTF-8?q?code=20format=20tools=20to=20PR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- spec-0010/index.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index d087ebc4..aea02eb4 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -21,18 +21,18 @@ 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 +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. +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 +A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. ### Guiding Principles @@ -55,11 +55,13 @@ notable changes for each version of a project. - **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 @@ -73,10 +75,11 @@ 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. + +- 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 From 90d63963a2ec8d747f7d66d0cdb98d19fafbd792 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Fri, 4 Oct 2024 19:36:30 -0400 Subject: [PATCH 03/10] Update spec-0010/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lars Grüter --- spec-0010/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index aea02eb4..c75abce7 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -43,7 +43,7 @@ notable changes for each version of a project. - Make versions and sections linkable. - List the most recent version first. - Display the release date for each version. -- Indicate if you follow Semantic Versioning. +- Indicate the type of release: minor, patch, pre-, ... ### Types of Changes From 9da9a558f3fc2b7dc83c7e5c33842e5b751ca009 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Fri, 4 Oct 2024 19:37:45 -0400 Subject: [PATCH 04/10] Update spec-0010/index.md Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com> --- spec-0010/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index c75abce7..eb15da70 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -62,7 +62,7 @@ ADD EXAMPLES ### Naming the Changelog File -CHANGELOG, HISTORY, NEWS, or RELEASES are widely accepted names for changelog files. +CHANGELOG, CHANGES, HISTORY, NEWS, or RELEASES are widely accepted names for changelog files. ### GitHub Releases From b781266fbc67453ce80af24ffe7382f5b8c88824 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Fri, 4 Oct 2024 20:20:41 -0400 Subject: [PATCH 05/10] Incorporate feedback --- spec-0010/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index eb15da70..2394fcf6 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -32,7 +32,7 @@ It promotes transparency and trust between the project’s leadership team, deve ### What Is a Changelog? -A changelog is a file which contains a curated, chronologically ordered list of +A changelog is a file which contains a curated list of notable changes for each version of a project. ### Guiding Principles @@ -44,7 +44,10 @@ notable changes for each version of a project. - 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. + ### Types of Changes - **Added**: New features. From 585ba4e4a40688a1fd85799bbf324ee9231b1aa3 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Fri, 4 Oct 2024 20:34:30 -0400 Subject: [PATCH 06/10] Update the Guiding Principles section --- spec-0010/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index 2394fcf6..7c56e78a 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -47,7 +47,9 @@ notable changes for each version of a project. - 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. + ### Types of Changes - **Added**: New features. From 1e6f765b88adfe7954f638e28f275857c8ab71f1 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Fri, 4 Oct 2024 21:52:51 -0400 Subject: [PATCH 07/10] Update the GitHub Releases section --- spec-0010/index.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index 7c56e78a..c222aacd 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -71,7 +71,42 @@ CHANGELOG, CHANGES, HISTORY, NEWS, or RELEASES are widely accepted names for cha ### GitHub Releases -TO DO +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 ### Automation From d3ba716a2e58342138bef4d23a411723385bab53 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Fri, 4 Oct 2024 22:31:24 -0400 Subject: [PATCH 08/10] Update the Types of Changes section --- spec-0010/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index c222aacd..fd875873 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -52,12 +52,12 @@ mentioned above. ### 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. +- **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 ### Standard Changelog Format From 82d19b1939f11e2f84b5cafcec0c3ac9299c1ca1 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 7 Oct 2024 13:32:00 +0000 Subject: [PATCH 09/10] =?UTF-8?q?[pre-commit.ci=20=F0=9F=A4=96]=20Apply=20?= =?UTF-8?q?code=20format=20tools=20to=20PR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- spec-0010/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index fd875873..2c615e9b 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -45,10 +45,10 @@ notable changes for each version of a project. - 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. + 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. + mentioned above. ### Types of Changes @@ -79,10 +79,10 @@ The most common approaches are: 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). +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 +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 @@ -98,14 +98,14 @@ This approach is adopted by ADD PROJECTS 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. +"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' +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, +For more info about releasing projects on GitHub, refer to: https://docs.github.com/en/repositories/releasing-projects-on-github ### Automation From 03328c9cd0ddf91fcc99ad7d2fbd5b9317849398 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Tue, 8 Oct 2024 15:29:26 -0400 Subject: [PATCH 10/10] Clarify the objectives of the SPEC --- spec-0010/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-0010/index.md b/spec-0010/index.md index 2c615e9b..07b7c03c 100644 --- a/spec-0010/index.md +++ b/spec-0010/index.md @@ -10,7 +10,7 @@ endorsed-by: ## Description -SPEC 10 provides guidelines and best practices for maintaining a changelog file +SPEC 10 provides guidelines for creating and maintaining documentation related to releases for libraries in the Scientific Python ecosystem. ### Core Project Endorsement