Proposal: Adopt GitHub CI to Auto-Generate Changelogs

[WangzJi]

Hi community,

Maintaining CHANGES.md manually during each release is error-prone and time-consuming. I’d like to propose using GitHub CI (specifically release-drafter) to automatically generate changelogs based on merged pull requests.

This will bring several benefits:

Benefits
Save time: Automatically collects and formats changelog entries when PRs are merged.
Less prone to mistakes: No need to manually copy and organize changes.
Consistent formatting: Grouped by labels like type: feature, type: fix, etc.
Better contributor visibility: Contributors get properly credited in the release notes.

Proposed Workflow
Add a .github/release-drafter.yml file with a changelog template.
Tag PRs with appropriate labels (e.g., type: optimize, type: test, etc.).
Enable a GitHub Action to update the draft release automatically on each PR merge.
Optionally, replace or synchronize CHANGES.md with the generated release notes.

Open Questions
Should we fully migrate away from CHANGES.md, or keep it and sync the content?
Would you prefer changelogs to be published only at release time or updated continuously as PRs land?
Any concerns about adopting this workflow from the release manager's perspective?

References
https://github.com/release-drafter/release-drafter

[YongGoose]

The project hasn’t been maintained for the past 5 months. Wouldn’t that make it difficult to fix bugs if any arise?
I believe adopting a project that is no longer actively maintained can be risky.

WDYT?

[YongGoose]

But still, I believe this approach is beneficial in the long run.
It might also be worth exploring if there are any libraries that offer similar functionality.

Alternatively, looking into how other popular projects manage their changelogs could provide some helpful insights.

[WangzJi]

Thank you for raising this important concern, @YongGoose! You're absolutely right to be cautious about adopting tools that might have maintenance issues. This is a valid point that deserves careful consideration.

Addressing the Maintenance Concern

While release-drafter hasn't seen recent commits, it's worth noting that:

1. Mature and stable: The tool has been around for years and is quite mature. Many projects continue using it successfully despite the slower update pace.
2. Active usage: Several major projects still rely on it:
   apache/maven
   jenkinsci/jenkins
3. Simple functionality: The core functionality is relatively straightforward - it's essentially template-based text generation, which is less likely to break with GitHub API changes.

Alternative Solutions

That said, your point about exploring alternatives is excellent. Here are some actively maintained options:

• release-please(Google) - Conventional commits + automatic versioning
• GitHub's built-in Release Notes - Zero maintenance, native integration

Proposed Path Forward

Given your feedback, I suggest we evaluate multiple options:

• Phase 1: Research and prototype with 2-3 different tools
• Phase 2: Test them on a few minor releases
• Phase 3: Choose the best fit based on our workflow and maintenance preferences

Would you be interested in helping evaluate these alternatives? I think having multiple perspectives would lead to a better decision for the project.
What are your thoughts on this approach? Any particular tools from this list that seem more appealing from a maintenance perspective?

[YongGoose]

It would be great if the results could be presented in a way that’s easy to see at a glance.

• https://www.jenkins.io/changelog/

If possible, please try experimenting in your local repository first and create a PR with the results.

release-please also looks like a good option.
You can try implementing both and compare them, or just choose one—it’s totally up to you.

[WangzJi]

Thanks for the suggestion! I agree that integrating the changelog into the official website could be useful, but for this discussion, my main focus is on the changelog specifically for GitHub releases.
I’ll I will evaluate which one is the best fit for our needs. Once I have some concrete results, I’ll update the discussion.

Thanks again for your input!

[funky-eyes]

I have a question. Since the description in the title is usually a brief overview, while the PR registration might be more detailed and could also support multiple languages, does this component provide such support?

[WangzJi]

Good point @funky-eyes! I guess when you mentioned "support multiple languages," you were referring to generating multilingual changelogs simultaneously, right?

For detailed PR information: Release-drafter can extract comprehensive details from PR bodies, not just titles. We can use custom templates to pull specific sections from PR descriptions.

For multi-language support: While release-drafter doesn't natively support this, we can run separate workflows with language-specific templates to generate both English and Chinese changelogs from the same PR data.

This would leverage the detailed PR information while maintaining our bilingual changelog structure.

[funky-eyes]

Good point @funky-eyes! I guess when you mentioned "support multiple languages," you were referring to generating multilingual changelogs simultaneously, right?

For detailed PR information: Release-drafter can extract comprehensive details from PR bodies, not just titles. We can use custom templates to pull specific sections from PR descriptions.

For multi-language support: While release-drafter doesn't natively support this, we can run separate workflows with language-specific templates to generate both English and Chinese changelogs from the same PR data.

This would leverage the detailed PR information while maintaining our bilingual changelog structure.

It looks good. Could you provide an example? For instance, by introducing this feature into your personal repository and then presenting the final effect for us to review.

[WangzJi]

Hi @funky-eyes @YongGoose , I’ve created a demo using release-please, which you can check out here:
👉 Demo Repository
Here is the generated CHANGELOG.md:
👉 CHANGELOG.md

While the current setup works, there are still a few things to optimize.

I have a few questions:

If the release notes are generated like in the example above, do we still need to maintain the CHANGELOG.md file via release-please, or is it redundant?

What are the best practices for managing both GitHub release notes and the CHANGELOG.md? Should we treat the changelog as a historical archive, or rely entirely on GitHub Releases?

[YongGoose]

Hmm… I think we need to clarify the role of the changelog.