Automate the generation changelogs in text format #480

soham30rane · 2024-11-23T13:30:07Z

Fixes #471 as discussed on sage-devel 2024-11-13

Necessary steps to take before achieving proper functionality:

Create Personal Access Token and add it to repo > Settings > Secrets and Variables > Actions > Repository Secrets
with name PERSONAL_ACCESS_TOKEN
Add another secret with name CHANGELOG_TRIGGER_SECRET.
Also add both the secrets to sage repo with the exact same names and values.

I am also making a pr to sage repo to define a workflow which will in turn trigger generate_changelog.yml on every release.

Sample results of the script. (Executed it for release tag 10.5, which considered all pre-releases uptil now)
sage-10.5.txt

kwankyu · 2024-11-24T12:03:31Z

scripts/create_changelog.py

+        file.write(f"Sage {ver} was released on {date_of_release}. It is available from:\n\n")
+        file.write(f"  * https://www.sagemath.org/download-source.html\n\n")
+        file.write(f"Sage (http://www.sagemath.org/) is developed by volunteers and\n")
+        file.write(f"combines hundreds of open source packages.\n\n")


It is a slight deviation from the tradition, but it may be better to use (http://www.sagemath.org) with no trailing slash for a new start.

kwankyu · 2024-11-24T12:04:45Z

scripts/create_changelog.py

+        file.write(f"Of those, {len(first_contribs)} made their first contribution to Sage:\n\n")
+        for c in all_contribs:
+            file.write(f"  - {c}{' [First Contribution]' if c in first_contribs else ''}\n")
+        pr_count = sum([len(all_info[tag]) for tag in all_info])


[First contribution] to align with other bracketed phrases.

kwankyu · 2024-11-24T12:06:32Z

Can I see an example run of the workflow?

…agemath.org)

dimpase · 2024-11-24T15:07:14Z

I wonder about the need for PAT here. Can it be explained?

…ther bracketed phrases

soham30rane · 2024-11-24T15:35:06Z

Can I see an example run of the workflow?

This commit is result of an example run of the workflow.
I triggered it mannually with the release tag of 10.0.
You could have a look here. The previous trigger failed because I forgot to add PERSONAL_ACCESS_TOKEN to the repo secrets.

Actually the workflow in this repo is expected to be triggered by this workflow to be located in main sage repo

soham30rane · 2024-11-24T15:41:35Z

I wonder about the need for PAT here. Can it be explained?

PAT is required for using Github REST API

Need for Github REST API: Everytime a release occurs on main sage repo, it triggers the generation of changelog in this repo. To generate changelog, the script uses info from the release notes (which is fetched via Github API).
But even if we somehow manage to get the release note info available to the script without using the API, it is not enough, because it doesn't contain the reviewer info and multiple authors info for PRs.
Hence Github API is needed to individually fetch info about each of the PRs.

dimpase · 2024-11-24T16:47:25Z

But isn't PAT only needed for the user running this particular Actions workflow?
This user need not be the user who submitted their PR. In our workflow, it can be a maintainer.

This action can be run by someone who has rights to approve the PR changing contributor's info. Other users don't seem to need a PAT, right?

soham30rane · 2024-11-24T18:19:42Z

Other users don't seem to need a PAT, right?

Yes, you are right, only a single PAT needs to be created (by a maintainer) and stored in repository secrets.

This action can be run by someone who has rights to approve the PR changing contributor's info

Yes! And I just realized that we don't need CHANGELOG_TRIGGER_SECRET to verify the source of trigger, because the PAT is already ensuring that only those people who have rights to approve the PR can trigger the workflow via API call. Should I go ahead and do the related cleanup?

dimpase · 2024-11-24T18:56:49Z

I admit don't have a complete understanding of Actions permissions model - please proceed as you see fit.

kwankyu · 2024-11-25T04:19:39Z

.github/workflows/generate_changelog.yml

+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "Added changelog for release: ${{ inputs.release_tag }}"
+          git push


Could the user.name and user.email be simpler?

We may use a specific file name (src/changelogs/sage-......txt?) instead of . for safety?

Could the user.name and user.email be simpler?

Yes we could do that, but if we change the email then we won't see the black github-actions icon in the commits. Instead we would see it in gray disabled mode.

We may use a specific file name (src/changelogs/sage-......txt?) instead of . for safety?

Yes, will fix that

kwankyu · 2024-11-25T04:28:13Z

scripts/create_changelog.py

+
+It fetches release data, extracts relevant pull request (PR) information, and generates a detailed changelog
+and add its to src/changelogs.
+The script uses the GitHub REST API to collect information about contributors, PR authors, and reviewers.


add it to

kwankyu · 2024-11-25T04:49:48Z

scripts/create_changelog.py

+
+def get_latest_tags():
+    url = f"{BASE_URL}/tags?per_page=1000"  # If per_page is not specified then very few tags are fetched
+    try:


If we get recent tags in the first page, I think 100 would be enough.

kwankyu · 2024-11-25T04:54:46Z

src/changelogs/sage-10.0.txt

+#35637: Dima Pasechnik: Remark that WSL needs a lot of RAM [Reviewed by Tobias Diez]
+#35638: Matthias Koppe: `build/pkgs/python3/spkg-configure.m4`: Add depcheck for zlib [Reviewed by Dima Pasechnik]
+#35460: Kwankyu Lee: Update developer guide for workflows on github [Reviewed by Matthias Koppe, Sebastian Oehms]
+


Previous changelogs do not have an empty line at the end.

kwankyu · 2024-11-25T05:12:30Z

scripts/create_changelog.py

+    global first_contribs
+    all_contribs = set([git_to_name.get(c, f"@{c}") for c in all_contribs])
+    first_contribs = set([git_to_name.get(c, f"@{c}") for c in first_contribs])
+


It seems that we can retrieve the github user's real name via github api from his/her github account name. If this is the case, then we may create a new entry in conf/contributors.xml and then use the real name instead of the github account name in the created changelog. For example, we may create this entry

<contributor name="Marie Bonboire" github="marizee"/>

and use "Marie Bonboire" instead of @marizee. The entries in contributors.xml are listed in alphabetical order in the last name. We may use the fact to find the right place to put the new entry in.

But this is out of the scope of this PR. You may decide to do this extra work or not. Just let me know.

Yes, this is doable, but some users might not have their real name on their Github Profile, in such case we seem to have no other option than to user their github username in the format @github-username.
I will work on it

Additionally, we can retrieve the location of the user (if available on their GitHub profile). Then, for all contributors who have their GitHub username in conf/contributors.xml but don't have location information, we can add it.

I think it would be better to tackle this in a separate script, so I may put together another PR specifically for adding the location data

kwankyu · 2024-11-25T06:00:32Z

... only a single PAT needs to be created (by a maintainer) and stored in repository secrets.

It seems that the sagemath organization owner (not the admin of sagemath/sage repo) can create a PAT that allows (read)-access to sagemath/sage repo, and then the admin of sagemath/website should store the PAT as a secret of sagemath/sage repo.

Do you confirm this?

soham30rane · 2024-11-26T12:02:40Z

Yes, I confirm that the sagemath organization owner can create a PAT, that allows read-access to sagemath/sage (since sagemath/sage is a public repo, giving 'read access to public repos' is also enough). BUT the PAT needs to be stored as a secret for both repos sagemath/website and sagemath/sage.

I will try to elaborate on the use of PAT here: (Its used in two parts)

In create_changelog.py which will be located in sagemath/website. Here its used to retrieve PR related info using Github API
In this workflow which will be located in sagemath/sage. Here its used to trigger generate_changelog.yml workflow after each release via Github API which will generate the changelog.

So for the 1st use case any valid PAT with 'read-access to public repos' will work. (And it should be stored in sagemath/website)
For 2nd use case, the PAT used has to belong to person who has rights to trigger a workflow run in sagemath/website (Obviously the org owner will have those rights). (And it should be stored in sagemath/sage)

This is the reason we need to store PAT in secrets of both repos sagemath/website and sagemath/sage. So we can store the PAT created by org owner (that allows read access to public repos) in secrets of both repos.

kwankyu · 2024-11-26T14:11:01Z

For public repos, no PAT may be necessary (or so my AI says :-) We could experiment soon.

soham30rane · 2024-11-26T15:48:59Z

I tried running the workflow without a PAT, and it worked perfectly! Sorry for the confusion earlier, also thank you for your patience.
That said, for the second use case I mentioned, a PAT is still necessary. If you'd prefer to avoid creating a PAT, you could just sideline it and manually trigger generate_changelog.yml after every release. Whatever works best for the org!

soham30rane · 2024-11-27T05:55:35Z

Okay, so the last time I triggered the workflow on my testing repo I had put a limit on the number of PRs fetched (just for the sake of saving time) and it seemed to work perfectly fine.
Today I ran the workflow after removing that limit and it gave me 'rate limit reached'.
I skimmed through their official documentation, and here they say The primary rate limit for unauthenticated requests is 60 requests per hour. This is not enough as there are more than 60 PRs in any stable release

kwankyu · 2024-11-27T07:13:24Z

So with a PAT, the rate limit is 5000 PRs? This would be big enough.

soham30rane · 2024-11-27T08:29:59Z

Yeah, 5000 would be more than enough.

haraldschilly · 2024-11-27T09:18:39Z

I'm not sure what's going on and how this is supposed to work, but I just opened the settings and saw there are also "Organization secrets" (and there is one for PYPI).

When I open the management form for that secret, I can add one there and tell it exactly which repositories should have access. So, I'm only guessing, but maybe you want the same secret (with the same value) to appear in two repositories? Then we could make this such an org secret for two repositories.

kwankyu · 2024-11-27T10:10:46Z

We can proceed in this way: Harald, as you are one of the organization owners, you can designate me as an admin of sagemath/website. Then I can work with the author to put his code in the repo, and then we can test how it works. And then if we need a PAT (perhaps but I am not sure yet), then you, as an organization owner, could make one for us. Then I can put that PAT as a secret to either repo sagemath/website or sagemath/sage as necessary.

dimpase · 2024-11-27T14:14:54Z

I think it's better to have different PATs for different repos, just as with the usual passwords

soham30rane added 2 commits November 23, 2024 12:17

Added Automation for generating changelogs

414b9f8

Update generate_changelog.yml, updated name of secret variable

4243d86

soham30rane mentioned this pull request Nov 23, 2024

Automated the generation of changelogs in text format sagemath/sage#39024

Open

5 tasks

kwankyu reviewed Nov 24, 2024

View reviewed changes

Updated create_changelog.py: Removed trailing slash for (http://www.s…

cabf502

…agemath.org)

soham30rane and others added 2 commits November 24, 2024 15:12

Updated create_changelog.py: now '[First Contribution]' aligns with o…

f96158d

…ther bracketed phrases

Added changelog for release: 10.0

38ccbd3

kwankyu reviewed Nov 25, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Automate the generation changelogs in text format #480

Automate the generation changelogs in text format #480

soham30rane commented Nov 23, 2024

kwankyu Nov 24, 2024

soham30rane Nov 24, 2024 •

edited

Loading

kwankyu Nov 24, 2024

soham30rane Nov 24, 2024

kwankyu commented Nov 24, 2024

dimpase commented Nov 24, 2024

soham30rane commented Nov 24, 2024 •

edited

Loading

soham30rane commented Nov 24, 2024

dimpase commented Nov 24, 2024

soham30rane commented Nov 24, 2024

dimpase commented Nov 24, 2024

kwankyu Nov 25, 2024

soham30rane Nov 26, 2024

kwankyu Nov 25, 2024

kwankyu Nov 25, 2024

kwankyu Nov 25, 2024

kwankyu Nov 25, 2024

soham30rane Nov 26, 2024

soham30rane Nov 26, 2024

kwankyu commented Nov 25, 2024 •

edited

Loading

soham30rane commented Nov 26, 2024

kwankyu commented Nov 26, 2024

soham30rane commented Nov 26, 2024

soham30rane commented Nov 27, 2024

kwankyu commented Nov 27, 2024

soham30rane commented Nov 27, 2024

haraldschilly commented Nov 27, 2024

kwankyu commented Nov 27, 2024 •

edited

Loading

dimpase commented Nov 27, 2024

Automate the generation changelogs in text format #480

Are you sure you want to change the base?

Automate the generation changelogs in text format #480

Conversation

soham30rane commented Nov 23, 2024

Choose a reason for hiding this comment

soham30rane Nov 24, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwankyu commented Nov 24, 2024

dimpase commented Nov 24, 2024

soham30rane commented Nov 24, 2024 • edited Loading

soham30rane commented Nov 24, 2024

dimpase commented Nov 24, 2024

soham30rane commented Nov 24, 2024

dimpase commented Nov 24, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwankyu commented Nov 25, 2024 • edited Loading

soham30rane commented Nov 26, 2024

kwankyu commented Nov 26, 2024

soham30rane commented Nov 26, 2024

soham30rane commented Nov 27, 2024

kwankyu commented Nov 27, 2024

soham30rane commented Nov 27, 2024

haraldschilly commented Nov 27, 2024

kwankyu commented Nov 27, 2024 • edited Loading

dimpase commented Nov 27, 2024

soham30rane Nov 24, 2024 •

edited

Loading

soham30rane commented Nov 24, 2024 •

edited

Loading

kwankyu commented Nov 25, 2024 •

edited

Loading

kwankyu commented Nov 27, 2024 •

edited

Loading