Skip to content

Release notes: 2 level of changelog #5271

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

Merged
fingolfin merged 5 commits into from
Sep 12, 2025
+119 −32
Merged

Release notes: 2 level of changelog #5271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e92b995
First attempt at 2 level changelog
aaruni96 Sep 5, 2025
2c9d6f6
dont silently lose PRs
aaruni96 Sep 5, 2025
dc6ccf4
Add missing bug labels
aaruni96 Sep 10, 2025
0d6648c
Apply suggestions from code review
fingolfin Sep 10, 2025
b293d4a
Update changelog devdocs
aaruni96 Sep 12, 2025
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
92 changes: 68 additions & 24 deletions dev/releases/release_notes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,8 @@ def warning(s):
# the given label is put into the corresponding section; each PR is put into only one section, the first one
# one from this list it fits in.
# See also <https://github.com/gap-system/gap/issues/4257>.
prioritylist = [
["release notes: highlight", "Highlights"],

["renaming", "Renamings"],

topics = [
["release notes: highlight", "Highlights"],
["topic: algebraic geometry", "Algebraic Geometry"],
["topic: combinatorics", "Combinatorics"],
["topic: commutative algebra", "Commutative Algebra"],
Expand All @@ -99,24 +96,25 @@ def warning(s):
["topic: polyhedral geometry", "Polyhedral Geometry"],
["topic: toric geometry", "Toric Geometry"],
["topic: tropical geometry", "Tropical Geometry"],

["serialization", "Changes related to serializing data in the MRDI file format"],

["enhancement", "New features or extended functionality"],
["experimental", "Only changes experimental parts of OSCAR"],
["optimization", "Performance improvements or improved testing"],
["bug: crash", "Fixed bugs that could lead to crashes"],
["bug", "Other fixed bugs"],
["documentation", "Improvements or additions to documentation"],

["package: AbstractAlgebra", "Changes related to the package AbstractAlgebra"],
["package: AlgebraicSolving", "Changes related to the package AlgebraicSolving"],
["package: GAP", "Changes related to the package GAP"],
["package: Hecke", "Changes related to the package Hecke"],
["package: Nemo", "Changes related to the package Nemo"],
["package: Polymake", "Changes related to the package Polymake"],
["package: Singular", "Changes related to the package Singular"],

]
prtypes = [
["renaming", "Renamings"],
["serialization", "Changes related to serializing data in the MRDI file format"],
Copy link
Copy Markdown
Member

@fingolfin fingolfin Sep 9, 2025

Choose a reason for hiding this comment

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

Why is that a "prtype" and not a "topic"?

Copy link
Copy Markdown
Member Author

@aaruni96 aaruni96 Sep 10, 2025

Choose a reason for hiding this comment

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

In PR like #5246 , you have both serialization and topic: polyhedral geometry. So, in the multilevel changelog would put it under "Polyhedral geometry", and the subheading "serialization".

If we put serialization in topics, then one of these labels will be ignored (script puts a PR in the first topic which is matched)

["enhancement", "New features or extended functionality"],
["experimental", "Only changes experimental parts of OSCAR"],
["optimization", "Performance improvements or improved testing"],
["bug: wrong result", "Fixed bugs that returned incorrect results"],
["bug: crash", "Fixed bugs that could lead to crashes"],
Comment thread
aaruni96 marked this conversation as resolved.
["bug: unexpected error", "Fixed bugs that resulted in unexpected errors"],
["bug", "Other fixed bugs"],
["documentation", "Improvements or additions to documentation"],
]


Expand Down Expand Up @@ -209,28 +207,57 @@ def changes_overview(
totalPRs = len(prs)
print(f"Total number of PRs: {totalPRs}")
countedPRs = 0
for priorityobject in prioritylist:
for priorityobject in topics:
matches = [
pr for pr in prs_with_use_title if has_label(pr, priorityobject[0])
]
print("PRs with label '" + priorityobject[0] + "': ", len(matches))
print(matches)
countedPRs = countedPRs + len(matches)
if len(matches) == 0:
continue
relnotes_file.write("### " + priorityobject[1] + "\n\n")
for pr in matches:
relnotes_file.write(pr_to_md(pr))
prs_with_use_title.remove(pr)
relnotes_file.write("\n")
if priorityobject[1] == 'Highlights':
itervar = topics
else:
itervar = prtypes
for typeobject in itervar:
if typeobject[1] == priorityobject[1]:
continue
matches_type = [
pr for pr in matches if has_label(pr, typeobject[0])
]
print("PRs with label '" + priorityobject[0] + "' and type '" + typeobject[0] + "': ", len(matches_type))
if len(matches_type) == 0:
continue
relnotes_file.write(f"#### {typeobject[1]}\n\n")
for pr in matches_type:
relnotes_file.write(pr_to_md(pr))
prs_with_use_title.remove(pr)
matches.remove(pr)
matches_type.remove(pr)
relnotes_file.write('\n')
print(f"Remaining PRs: {totalPRs - countedPRs}")
# The remaining PRs have no "kind" or "topic" label from the priority list
# (may have other "kind" or "topic" label outside the priority list).
# Check their list in the release notes, and adjust labels if appropriate.
if len(prs_with_use_title) > 0:
relnotes_file.write("### Other changes\n\n")
for pr in prs_with_use_title:
relnotes_file.write(pr_to_md(pr))
relnotes_file.write("\n")
for typeobject in prtypes:
print(typeobject)
matches_type = [
pr for pr in prs_with_use_title if has_label(pr, typeobject[0])
]
len(matches_type)
print("PRs with label '" + priorityobject[0] + "' and type '" + typeobject[0] + "': ", len(matches_type))
if len(matches_type) == 0:
continue
relnotes_file.write("#### " + typeobject[1] + "\n\n")

for pr in matches_type:
relnotes_file.write(pr_to_md(pr))
prs_with_use_title.remove(pr)
relnotes_file.write("\n")

# Report PRs that have to be updated before inclusion into release notes.
prs_to_be_added = [pr for pr in prs if has_label(pr, "release notes: to be added")]
Expand All @@ -245,6 +272,23 @@ def changes_overview(
for pr in prs_to_be_added:
relnotes_file.write(pr_to_md(pr))
relnotes_file.write("\n")
if len(prs_with_use_title) > 0:
relnotes_file.write(
"### **TODO** insufficient labels for automatic classification\n\n"
"The following PRs only have a topic label assigned to them, not a PR type. Either "
"assign a type label to them (e.g., `enhancement`), or manually move them to the "
"general section of the topic section in the changelog.\n\n")
for pr in prs_with_use_title:
for topic in topics:
matches = [pr for pr in prs_with_use_title if has_label(pr, topic[0])]
if len(matches) == 0:
continue
relnotes_file.write(f'#### {topic[1]}\n\n')
for match in matches:
relnotes_file.write(pr_to_md(match))
prs_with_use_title.remove(match)
relnotes_file.write('\n')
relnotes_file.write('\n')

# remove PRs already handled earlier
prs = [pr for pr in prs if not has_label(pr, "release notes: to be added")]
Expand Down
59 changes: 51 additions & 8 deletions docs/src/DeveloperDocumentation/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,10 +60,17 @@ labelled. We have the following labels, along with how they are meant to be appl
In addition to the release notes action labels, you can tag your PR with these following
labels, and the release notes script will organize them appropriately:

#### Multi level topics

The changelog is organized into a 2 level structure: the topic, and the type. Each PR must have one
topic label, and one type label. The changes in each topic are then grouped by types, before moving
on to the next topic, which are also grouped by types, and so on.

##### PR Topics

| Label | Changelog Category |
|-------------------------------|--------------------|
| `release notes: highlight` | Highlights |
| `renaming` | Items being renamed |
| `topic: algebraic geometry` | Changes related to Algebraic Geometry |
| `topic: combinatorics` | Changes related to Combinatorics |
| `topic: commutative algebra` | Changes related to Commutative Algebra |
Expand All @@ -74,13 +81,6 @@ labels, and the release notes script will organize them appropriately:
| `topic: polyhedral geometry` | Changes related to Polyhedral Geometry |
| `topic: toric geometry ` | Changes related to Toric Geometry |
| `topic: tropical geometry` | Changes related to Tropical Geometry |
| `serialization` | Changes related to serializing data in the MRDI file format ? |
| `enhancement` | New features or extended functionality |
| `experimental` | Only changes experimental parts of OSCAR |
| `optimization` | Performance improvements or improved testing |
| `bug: crash` | Fixed bugs that could lead to crashes |
| `bug` | Other fixed bugs |
| `documentation` | Improvements or additions to documentation |
| `package: AbstractAlgebra` | Changes related to the package AbstractAlgebra |
| `package: AlgebraicSolving` | Changes related to the package AlgebraicSolving |
| `package: GAP` | Changes related to the package GAP |
Expand All @@ -89,6 +89,49 @@ labels, and the release notes script will organize them appropriately:
| `package: Polymake` | Changes related to the package Polymake |
| `package: Singular` | Changes related to the package Singular |

##### PR Types

| Label | Changelog Category |
|-------------------------------|--------------------|
| `renaming` | Items being renamed |
| `serialization` | Changes related to serializing data in the MRDI file format |
| `enhancement` | New features or extended functionality |
| `experimental` | Only changes experimental parts of OSCAR |
| `optimization` | Performance improvements or improved testing |
| `bug: wrong result` | Fixed bugs that returned incorrect results |
| `bug: crash` | Fixed bugs that could lead to crashes |
| `bug: unexpected error` | Fixed bugs that resulted in unexpected errors |
| `bug` | Other fixed bugs |
| `documentation` | Improvements or additions to documentation |

#### Example

As an example, the following PRs are rendered as follows:

> - PR #1337 with topic label `topic: groups`, and type label `optimization`
> - PR #1338 with topic label `package: Singular`, and type label `renaming`
> - PR #1339 with topic label `package: Singular`, and type label `experimental`

-----
>
> ### Groups
>
> #### Performance improvements or improved testing
>
> - [#1337] Lorem ipsum
>
> ### Changes related to the package Singular
>
> #### Renamings
>
> - [#1338] Foo bar
>
> #### Only changes experimental parts of OSCAR
>
> - [#1338] Alice bob
>
-----

## Suggestions for formulations

In general the description of each change should start with a verb in present
Expand Down
Loading