Create GitHub releases with changelogs

[lusu007]

Beyond just tagging, creating GitHub releases and including a changelog would be beneficial. This practice significantly helps users using automation tools such as Renovate or Dependabot. These tools can automatically append changelogs to the merge requests they open, thereby enhancing the efficiency and security of version updates.

GitHub can automatically generate changelogs for releases.

Furthermore, it is probably a good idea to automate the complete release process. For this process a tool like release-drafter could be used.

[adrienverge]

Hello Lukas and thanks for the report! This is an interesting idea. A changelog is already maintained in CHANGELOG.rst, so it would duplicate the process of writing entries (unless there's an automatic way of copying the former into the latter when tags are pushed), which I don't like because it can be error-prone and doubles the manual work. If we need to choose between CHANGELOG.rst and entries on the tags page specific to GitHub, I prefer the CHANGELOG file: it's more standard, it's present outside GitHub (on PyPI, in wheels and sdist files...), and this repo might not always stick to GitHub.

GitHub has the possibility to automatically generate changelogs for releases.

From what I read, this is either a manual process (one needs to create tags using the GitHub web interface), or you need a GitHub Enterprise Server instance. Is there a GitHub option to automatically fill GitHub releases notes when I git push --tags?

[lusu007]

Hey Adrien,

as far as I know, Renovate and Dependabot as well are not able to parse those CHANGELOG.rst files. Regarding your concerns about doubling the manual work, I suggest automating the whole release process. A GitHub action could do the work of writing the CHANGELOG.rst and the release notes for you. Furthermore, automation would replace manual uploads to PyPi or wherever you want to release this package.

Automating the whole process would lead to more transparency as every user could see how the package was built. If you are building and uploading the package manually using your computer you could inject malware or something else and we as end-users cant be sure whether the library is safe or not. Building and publishing using CI/CD immensely increases the security of the supply chain.

From what I read, this is either a manual process (one needs to create tags using the GitHub web interface), or you need a GitHub Enterprise Server instance. Is there a GitHub option to automatically fill GitHub releases notes when I git push --tags?

You cited the enterprise documentation but the changelog generation feature is available for free users as well on Github.com. (see here) Furthermore, a tool like release-drafter could generate Release notes from the commit messages by itself and does not need GitHub's generation feature.

[adrienverge]

Maybe I missed something, but the GitHub action and documentation you reference doesn't seem to apply to yamllint: our changelogs are not just the list of commit titles between 2 tags, it's a writing work that tries to be clear, concise and readable, and that a bot wouldn't do. I understand such automation is valuable for large projects with hundreds of commits in each release, but this is not the case here. I think that yamllint users should read the human-written CHANGELOG.rst rather than a bot-generated list.

[lusu007]

In my opinion, every entry in yamllint's CHANGELOG.rst file could be a commit message. If you strictly use conventional commits there is no need to write extra changelog entries.

Automation is valuable for every project. The time automation safes could be invested into fixing bugs or developing new features. Besides that automatic builds and releases would greatly increase the security of yamllint's deploy-chain, because the library is built on a trusted runner and somebody's private machine.

[adrienverge]

I understand. I suggest looking at yamllint commits between the last release and the one before, and to compare to the changelog. Although yamllint commits are atomic and their titles aim to be clear and well redacted (and previously used conventional commits specification), many of them would just burden the changelog and make it less useful and a pain to read. For example, between v1.34.0 (last release) and v1.33.0 there were 38 commits, vs. 6 entries in the CHANGELOG.rst. Some of the commits are just style-related, some commits were merged then unfortunately reverted, some documentation edits should be in the changelog but some others shouldn't, etc.

About automation, it's another subject, which I don't want to set-up for this project now.

[lusu007]

I got your point. A well-written changelog is better than a generated one with unnecessary messages.

Nonetheless, this project could significantly benefit from creating GitHub releases. By doing so, you enable automation tools like Renovate to parse the changelog and, if desired, publish binaries alongside the release. This approach enhances transparency and makes it easier to browse release changelogs.