Automate the generation changelogs in text format

[soham30rane]

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]

Can I see an example run of the workflow?

[dimpase]

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

[soham30rane]

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]

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]

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]

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]

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

[kwankyu]

... 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]

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)

1. In create_changelog.py which will be located in sagemath/website. Here its used to retrieve PR related info using Github API

2. 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]

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

[soham30rane]

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]

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]

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

[soham30rane]

Yeah, 5000 would be more than enough.

[haraldschilly]

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]

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]

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

[soham30rane]

I was wondering, how do we identify the release manager for a specific release? Is it mentioned explicitly somewhere, or is there a standard way to fetch this information? Or there isn't any?

[kwankyu]

Fortunately our release manager does not change :-) or it is a once or no event in a decade that we change the release manager. Volker Braun has been the release manager since 18 December 2013, when Sage 6.0 was released. I got this info from the changelogs!

Hence I think you may hard-code that info into your changelog template. Or if you want to be more systematic, you may create a small json, yaml or txt file that contains the info. I have no better idea.

[kwankyu]

I hoped that the commit of a release tag contains the name of the release manager, but it is not the case.

[soham30rane]

I’m done with the final touches and ready to proceed. Thank you!

[kwankyu]

Thanks!

[soham30rane]

@kwankyu I see the workflow failed because of branch protection (changes can only be made via pull requests).

We might need to update the workflow to create a PR instead of directly pushing. The manual step of merging the PR seems unavoidable but aligns well with the current protection rules of this repo. What do you think?

[kwankyu]

Yes, the branch protection rule was an obstacle. It could be overcome by making the workflow to use the PAT created by me (admin). I found that Dima is also an admin since he is in the Core group. It seems that the PAT stored as a secret is secure enough.

The workflow is now working well. I manually ran the workflow for 10.1, 10.2, 10.3, 10.4 (pending).

I made some other small fixes and manual edits for 10.0 changelog. You can check them in the last commits.

[kwankyu]

There is some obscurity about the release date. The workflow gets the release date from "published at" value of the release data. However the release data is created by a workflow in sagemath/sage, which could run at worst after a few days after the release manager makes a release (= push a release tag). I think there is nothing that the workflow here could do about that.

[soham30rane]

The response returned by Githup API has following two dates

"created_at": "2024-07-19T22:37:02Z",
"published_at": "2024-07-20T00:28:33Z",

This example is for tag 10.4
So it seems we have to fetch the created_at value from the response instead of published_at

[kwankyu]

Thanks. Yes, it seems better. I did it in 854c9c3

[dimpase]

@kwankyu - I've created a PAT, as requested. Where should it go? Can I upload/store it myself? Else, I can email it to you, encrypted. Do you have a pgp/gnu-pg/gpg key?

[kwankyu]

Dima, sorry for lately informing you about what's going on.

As explained in #480 (comment), I realized that since you are in the Core group, the PATs created by you are as (perhaps more) powerful than mine. Thus and also to overcome the branch protection rule obstacle, I created SAGE_ACCESS_TOKEN, and saved it in sagemath/website as a secret.

For WEBSITE_ACCESS_TOKEN, I think it is also simpler and safer for me to create a PAT and directly save it to sagemath/sage as a secret.

[kwankyu]

Just now I ran the workflow manually for the release 10.5.
The workflow ran well. But the generated changelog for 10.5 has a problem.
The list of "merged PRs" for release 10.5 repeats all PRs merged in the prereleases!

What should be the solution:

(1) Fix the list of merged PRs included in the stable release (include only newly merged PRs for the release)

or

(2) Fix the workflow here to work only with the stable release (ignore prereleases)

?

See https://github.com/sagemath/sage/releases

[soham30rane]

We could update the workflow to fetch any pr only once (by keeping track of pr ids). This way even if any pr is mentioned twice (Once in pre-release and once in stable release), it will only be fetched once overall (first all prs in pre-releases will be fetched).

We can make following changes in create_changelog.py

# Global variable to store pr ids of feched prs
feched_prs = [] 

# Rest of the code . . .

# To be inserted at line 252
if pr_id in fetched_prs:
    continue
else:
    feched_prs.append(pr_id)

Should I open another pr for it ?

[kwankyu]

The simplest fix seems to be

(1) Fix the list of merged PRs included in the stable release (include only newly merged PRs for the release)

For now I modified https://github.com/sagemath/sage/releases/tag/10.5 and regenerated the changelog for release 10.5 by running the workflow again. Now we have the correct changelog.

[kwankyu]

Should I open another pr for it ?

No. Let's keep the workflow as it is. Thanks.

[kwankyu]

By the way, @haraldschilly updated the website. See the updated page: https://www.sagemath.org/development-map.html

Thank @haraldschilly and @soham30rane!

[dimpase]

(1) is highly non-standard, and I think nothing is lost by doing (2) instead. Besides, (2) can be done by a standard GitHub action.