github-starred/gitea
2
0
Fork 0
mirror of https://github.com/go-gitea/gitea.git synced 2026-03-10 22:06:34 -05:00
Code Issues 2.6k Packages Projects Releases 100 Wiki Activity

New approach to changelog management #3226

New Issue
Closed
opened 2025-11-02 05:04:39 -06:00 by GiteaMirror · 20 comments
GiteaMirror commented 2025-11-02 05:04:39 -06:00
Owner
Copy Link

Originally created by @jolheiser on GitHub (Apr 22, 2019).

Currently, our approach to changelogs is working, however as we continue to have more PRs it starts to become unwieldy.
As an example, more often than not when making a changelog/blog post, each commit/PR needs to be checked for proper capitalization, wording, etc.

Currently we use our internal changelog "generator" which relies on hitting GitHub's API and puts PRs into piles based on tags and uses their title.

This issue is meant to discuss possible alternatives and whether they are needed or would provide benefit to the project.

As more alternatives are mentioned, I can add them to the below list.

Current proposed alternatives

Gitlab's approach to changelogs, requiring each commit/PR to be accompanied by a YAML file describing the change, which would then be used to generate the changelog.

Conventional Commits, which would require specifically styled commit messages that would be used to generate the changelog.

Originally created by @jolheiser on GitHub (Apr 22, 2019). Currently, our approach to changelogs is working, however as we continue to have more PRs it starts to become unwieldy. As an example, more often than not when making a changelog/blog post, each commit/PR needs to be checked for proper capitalization, wording, etc. Currently we use our [internal changelog "generator"](https://github.com/go-gitea/changelog) which relies on hitting GitHub's API and puts PRs into piles based on tags and uses their title. This issue is meant to discuss possible alternatives and whether they are needed or would provide benefit to the project. As more alternatives are mentioned, I can add them to the below list. ### Current proposed alternatives [Gitlab's approach to changelogs](https://docs.gitlab.com/ee/development/changelog.html), requiring each commit/PR to be accompanied by a YAML file describing the change, which would then be used to generate the changelog. [Conventional Commits](https://www.conventionalcommits.org/), which would require specifically styled commit messages that would be used to generate the changelog.
GiteaMirror added the type/proposaltype/docs labels 2025-11-02 05:04:39 -06:00
GiteaMirror commented 2025-11-02 05:04:40 -06:00
Author
Owner
Copy Link

@jolheiser commented on GitHub (Apr 22, 2019):

@go-gitea/maintainers pinging for feedback.

@jolheiser commented on GitHub (Apr 22, 2019): @go-gitea/maintainers pinging for feedback.
GiteaMirror commented 2025-11-02 05:04:40 -06:00
Author
Owner
Copy Link

@techknowlogick commented on GitHub (Apr 22, 2019):

Another alternative is https://www.conventionalcommits.org/

although this would require more effort on the effort of developers worrying about their commits messages, and might need to have devs squash their commits (so the squash/merge commit into master isn't cluttered with WIP commits).

Edit: I should note, I am for switching to GitLab style changelog rather than enforcing a commit style (or PR title style) because it would allow a cleaner changelog, as some PRs are minor updates for others and probably don't need an entry in the changelog.

@techknowlogick commented on GitHub (Apr 22, 2019): Another alternative is https://www.conventionalcommits.org/ although this would require more effort on the effort of developers worrying about their commits messages, and might need to have devs squash their commits (so the squash/merge commit into master isn't cluttered with WIP commits). Edit: I should note, I am for switching to GitLab style changelog rather than enforcing a commit style (or PR title style) because it would allow a cleaner changelog, as some PRs are minor updates for others and probably don't need an entry in the changelog.
GiteaMirror commented 2025-11-02 05:04:40 -06:00
Author
Owner
Copy Link

@markusamshove commented on GitHub (Apr 23, 2019):

I want to take the chance and ask if you could build a link into the changelog that goes to a diff of the example app ini, comparing it to the previous version, because that's what I'm doing manually to see if I have to/can configure something new

@markusamshove commented on GitHub (Apr 23, 2019): I want to take the chance and ask if you could build a link into the changelog that goes to a diff of the example app ini, comparing it to the previous version, because that's what I'm doing manually to see if I have to/can configure something new
GiteaMirror commented 2025-11-02 05:04:40 -06:00
Author
Owner
Copy Link

@lunny commented on GitHub (Apr 25, 2019):

@MarkusAmshove I thinks that's off topic. You can fire another issue to do that.

@lunny commented on GitHub (Apr 25, 2019): @MarkusAmshove I thinks that's off topic. You can fire another issue to do that.
GiteaMirror commented 2025-11-02 05:04:40 -06:00
Author
Owner
Copy Link

@guillep2k commented on GitHub (Nov 14, 2019):

Gitlab's approach to changelogs, requiring each commit/PR to be accompanied by a YAML file describing the change, which would then be used to generate the changelog.

How does this work? Is the .yml file part of the commit? Is it somewhere in the PR comments?

I see, the YAML will be part of the PR. I'm not comfortable with such approach:

  • Quick fixes will be more bureaucratic.
  • It's a little taxing on contributors. We will be asking them to write in understandable English, install a new tool., etc.
  • Online edits (e.g. typos) will be hurt by this practice.
  • I think it's easier for a maintainer/manager to suggest a title change rather than suggest changes in the yml.
  • Sometimes the PR effect depends on the context; it could be decided later whether to include it or not, it's classification, the [Changelog] label...

I don't know if there can be some editorial action before creating the final changelog, but there should be one anyway, since the importance of some PRs is contextual to what other PRs were included. So, a final revision of the changelog is somewhat unavoidable.

@guillep2k commented on GitHub (Nov 14, 2019): > [Gitlab's approach to changelogs](https://docs.gitlab.com/ee/development/changelog.html), requiring each commit/PR to be accompanied by a YAML file describing the change, which would then be used to generate the changelog. ~~How does this work? Is the .yml file part of the commit? Is it somewhere in the PR comments?~~ I see, the YAML will be part of the PR. I'm not comfortable with such approach: * Quick fixes will be more bureaucratic. * It's a little taxing on contributors. We will be asking them to write in understandable English, install a new tool., etc. * Online edits (e.g. typos) will be hurt by this practice. * I think it's easier for a maintainer/manager to suggest a title change rather than suggest changes in the yml. * Sometimes the PR effect depends on the context; it could be decided later whether to include it or not, it's classification, the `[Changelog]` label... I don't know if there can be some editorial action before creating the final changelog, but there _should be one anyway_, since the importance of some PRs is contextual to what other PRs were included. So, a final revision of the changelog is somewhat unavoidable.
GiteaMirror commented 2025-11-02 05:04:41 -06:00
Author
Owner
Copy Link

@jolheiser commented on GitHub (Nov 14, 2019):

This issue may be a partial duplicate of #505 as well...

@jolheiser commented on GitHub (Nov 14, 2019): This issue may be a partial duplicate of #505 as well...
GiteaMirror commented 2025-11-02 05:04:41 -06:00
Author
Owner
Copy Link

@jolheiser commented on GitHub (Nov 14, 2019):

Now that I've read through #505, I see we would even have a potential starting point with https://gitlab.com/bkc/changelogger

@jolheiser commented on GitHub (Nov 14, 2019): Now that I've read through #505, I see we would even have a potential starting point with https://gitlab.com/bkc/changelogger
GiteaMirror commented 2025-11-02 05:04:41 -06:00
Author
Owner
Copy Link

@jolheiser commented on GitHub (Nov 14, 2019):

Quick fixes will be more bureaucratic.

Not necessarily. Do all quick fixes need a changelog entry? Currently they are all included, but perhaps they don't need to be?

It's a little taxing on contributors. We will be asking them to write in understandable English, install a new tool., etc.

We could always make suggestions, or even add a changelog entry for them after the fact if needed.

Online edits (e.g. typos) will be hurt by this practice.

I don't understand?

I think it's easier for a maintainer/manager to suggest a title change rather than suggest changes in the yml.

Perhaps, but that also required the author to change their PR title.

Sometimes the PR effect depends on the context; it could be decided later whether to include it or not, it's classification, the [Changelog] label...

I agree, it would just be nice to have a better consensus before we make a changelog PR.

All that being said, I'm not all aboard the Gitlab train. I just think something should change, as our current process can be fickle.

@jolheiser commented on GitHub (Nov 14, 2019): > Quick fixes will be more bureaucratic. Not necessarily. Do all quick fixes need a changelog entry? Currently they are all included, but perhaps they don't need to be? > It's a little taxing on contributors. We will be asking them to write in understandable English, install a new tool., etc. We could always make suggestions, or even add a changelog entry _for them_ after the fact if needed. > Online edits (e.g. typos) will be hurt by this practice. I don't understand? > I think it's easier for a maintainer/manager to suggest a title change rather than suggest changes in the yml. Perhaps, but that also required the author to change their PR title. > Sometimes the PR effect depends on the context; it could be decided later whether to include it or not, it's classification, the [Changelog] label... I agree, it would just be nice to have a better consensus _before_ we make a changelog PR. All that being said, I'm not all aboard the Gitlab train. I just think _something_ should change, as our current process can be fickle.
GiteaMirror commented 2025-11-02 05:04:41 -06:00
Author
Owner
Copy Link

@guillep2k commented on GitHub (Nov 14, 2019):

Online edits (e.g. typos) will be hurt by this practice.

I don't understand?

I mean, people that don't clone Gitea's repo but use the online editor to PR a quick fix. Those PR's are single file commits, usually. Granted, they can add more files later.

@guillep2k commented on GitHub (Nov 14, 2019): > > Online edits (e.g. typos) will be hurt by this practice. > > I don't understand? I mean, people that don't clone Gitea's repo but use the online editor to PR a quick fix. Those PR's are single file commits, usually. Granted, they can add more files later.
GiteaMirror commented 2025-11-02 05:04:41 -06:00
Author
Owner
Copy Link

@jolheiser commented on GitHub (Nov 14, 2019):

Online edits (e.g. typos) will be hurt by this practice.

I don't understand?

I mean, people that don't clone Gitea's repo but use the online editor to PR a quick fix. Those PR's are single file commits, usually. Granted, they can add more files later.

Ah, I see. That would fall under the semi-related "do those really need to be in the changelog in the first place?" discussion imo

@jolheiser commented on GitHub (Nov 14, 2019): > > > Online edits (e.g. typos) will be hurt by this practice. > > > > > > I don't understand? > > I mean, people that don't clone Gitea's repo but use the online editor to PR a quick fix. Those PR's are single file commits, usually. Granted, they can add more files later. Ah, I see. That would fall under the semi-related "do those really need to be in the changelog in the first place?" discussion imo
GiteaMirror commented 2025-11-02 05:04:42 -06:00
Author
Owner
Copy Link

@guillep2k commented on GitHub (Nov 14, 2019):

It seems to me that we should decide first on some kind of editorial rules on what needs to make it to the change log and how it should look like before deciding how that is actually implemented. 🤔

@guillep2k commented on GitHub (Nov 14, 2019): It seems to me that we should decide first on some kind of editorial rules on what needs to make it to the change log and how it should _look like_ before deciding how that is actually implemented. 🤔
GiteaMirror commented 2025-11-02 05:04:42 -06:00
Author
Owner
Copy Link

@lafriks commented on GitHub (Nov 14, 2019):

imho easiest and best way is to mark all PR's needed to be included in changelog to be marked with changelog label. We should fix PR title to be descriptive for changelog before merging

@lafriks commented on GitHub (Nov 14, 2019): imho easiest and best way is to mark all PR's needed to be included in changelog to be marked with changelog label. We should fix PR title to be descriptive for changelog before merging
GiteaMirror commented 2025-11-02 05:04:42 -06:00
Author
Owner
Copy Link

@sapk commented on GitHub (Nov 15, 2019):

I agree with @lafriks we can even easely edit title and labels of PR merged (not the commit) so we can also add PR by adding changelog label and edit title if not explicit. We could do a quick review of un-labeled changelog PR before release to see if some are missing.

@sapk commented on GitHub (Nov 15, 2019): I agree with @lafriks we can even easely edit title and labels of PR merged (not the commit) so we can also add PR by adding changelog label and edit title if not explicit. We could do a quick review of un-labeled changelog PR before release to see if some are missing.
GiteaMirror commented 2025-11-02 05:04:42 -06:00
Author
Owner
Copy Link

@lunny commented on GitHub (Nov 15, 2019):

How about make rules for PR's title and create a bot to check that and deny the merge before it matched the rules? And of course the bot could also check approvals count and add some labels. Teabot I think that should be a better method.

The bot could be a drone plugin and could be the first step of gitea's drone file or a standalone service which could accept webhooks.

@lunny commented on GitHub (Nov 15, 2019): How about make rules for PR's title and create a bot to check that and deny the merge before it matched the rules? And of course the bot could also check approvals count and add some labels. Teabot I think that should be a better method. The bot could be a drone plugin and could be the first step of gitea's drone file or a standalone service which could accept webhooks.
GiteaMirror commented 2025-11-02 05:04:42 -06:00
Author
Owner
Copy Link

@lunny commented on GitHub (Nov 15, 2019):

Since now is 9102, we should hire more bots to help us development. :(

@lunny commented on GitHub (Nov 15, 2019): Since now is 9102, we should hire more bots to help us development. :(
GiteaMirror commented 2025-11-02 05:04:43 -06:00
Author
Owner
Copy Link

@jolheiser commented on GitHub (Nov 15, 2019):

I am fine with the above options as long as the mergers/owners are willing to do the work since we cannot help with those. Don't want you guys to have to do everything manually yourselves 😄

@jolheiser commented on GitHub (Nov 15, 2019): I am fine with the above options as long as the mergers/owners are willing to do the work since we cannot help with those. Don't want you guys to have to do _everything_ manually yourselves :smile:
GiteaMirror commented 2025-11-02 05:04:43 -06:00
Author
Owner
Copy Link

@lunny commented on GitHub (Nov 15, 2019):

@jolheiser That's github's limitation. After we moved to gitea.com, we have a issueManager team then more maintainers could help to do these work. 😄

@lunny commented on GitHub (Nov 15, 2019): @jolheiser That's github's limitation. After we moved to gitea.com, we have a issueManager team then more maintainers could help to do these work. 😄
GiteaMirror commented 2025-11-02 05:04:43 -06:00
Author
Owner
Copy Link

@jolheiser commented on GitHub (Nov 15, 2019):

:exclamation::exclamation:❗ That's right! :exclamation:❗❗
I forgot about that.

@jolheiser commented on GitHub (Nov 15, 2019): :exclamation::exclamation::exclamation: That's right! :exclamation::exclamation::exclamation: I forgot about that.
GiteaMirror commented 2025-11-02 05:04:44 -06:00
Author
Owner
Copy Link

@bkcsoft commented on GitHub (Nov 15, 2019):

No longer an active member, but since my tool (and therefore I) got mentioned I'll throw in my 2 cents as well 🙂

as we continue to have more PRs it starts to become unwieldy.

As a project grows larger, its changelog will grow with it. Being selective about what goes in it is not going to change that. But not including quickfixes/type-Os would be a good start 🙂

As an example, more often than not when making a changelog/blog post, each commit/PR needs to be checked for proper capitalization, wording, etc.

This would still need to happen at some stage, whether its done like it is now, or in the PR itself (Owners can edit title and body), or in a YAML-file inside the commits, would not change this fact.

We will be asking them to write in understandable English, install a new tool., etc.

Someone needs to write it in understandable English, this could be done by the Contributor, or by an Owner (who has push-rights), or by a Bot (controlled by some factors).

And there would be no need for contributors to install a new tool, they'd only fill out a YAML-file. The tool would be used by maintainers/owners when they make the Release.

I think it's easier for a maintainer/manager to suggest a title change rather than suggest changes in the yml.

Perhaps, but that also required the author to change their PR title.

Not necessarily, Owners can change the PR title as well. This could be further setup with a bot (say /title-bot "new fancy title"), that has owner-status, so that other maintainers would have this access as well.

Sometimes the PR effect depends on the context; it could be decided later whether to include it or not, it's classification, the [Changelog] label...

PRs will extremely rarely have its changelog-worthyness changed after it's merged. When the PR is up for merge, it should be obvious whether it needs a changelog entry for it or not 🙂

imho easiest and best way is to mark all PR's needed to be included in changelog to be marked with changelog label.

This would be nice even if you go the YAML-route, have CI check if there's a changelog-file in the PR if [changelog] tag is set.

We should fix PR title to be descriptive for changelog before merging

This should be done even if you don't use PR title/body for changelogs. As it makes things more searchable from the PR-list 😉

@bkcsoft commented on GitHub (Nov 15, 2019): No longer an active member, but since my tool (and therefore I) got mentioned I'll throw in my 2 cents as well :slightly_smiling_face: > as we continue to have more PRs it starts to become unwieldy. As a project grows larger, its changelog will grow with it. Being selective about what goes in it is not going to change that. But not including quickfixes/type-Os would be a good start :slightly_smiling_face: > As an example, more often than not when making a changelog/blog post, each commit/PR needs to be checked for proper capitalization, wording, etc. This would still need to happen at some stage, whether its done like it is now, or in the PR itself (Owners can edit title and body), or in a YAML-file inside the commits, would not change this fact. > We will be asking them to write in understandable English, install a new tool., etc. Someone needs to write it in understandable English, this could be done by the Contributor, or by an Owner (who has push-rights), or by a Bot (controlled by some factors). And there would be no need for _contributors_ to install a new tool, they'd only fill out a YAML-file. The tool would be used by maintainers/owners when they make the Release. >> I think it's easier for a maintainer/manager to suggest a title change rather than suggest changes in the yml. > Perhaps, but that also required the author to change their PR title. Not necessarily, Owners can change the PR title as well. This could be further setup with a bot (say `/title-bot "new fancy title"`), that has owner-status, so that other maintainers would have this access as well. > Sometimes the PR effect depends on the context; it could be decided later whether to include it or not, it's classification, the [Changelog] label... PRs will _extremely_ rarely have its changelog-worthyness changed _after_ it's merged. When the PR is up for merge, it should be obvious whether it needs a changelog entry for it or not :slightly_smiling_face: > imho easiest and best way is to mark all PR's needed to be included in changelog to be marked with changelog label. This would be nice even if you go the YAML-route, have CI check if there's a changelog-file in the PR if [changelog] tag is set. > We should fix PR title to be descriptive for changelog before merging This should be done even if you don't use PR title/body for changelogs. As it makes things more searchable from the PR-list :wink:
GiteaMirror commented 2025-11-02 05:04:44 -06:00
Author
Owner
Copy Link

@lunny commented on GitHub (May 25, 2023):

As a discussion, I think we can close this one. If anyone has a better method for the changelog, he can create another proposal issue.

@lunny commented on GitHub (May 25, 2023): As a discussion, I think we can close this one. If anyone has a better method for the changelog, he can create another proposal issue.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
$20
$250
$50
$500
backport/done
💎 Bounty
docs-update-needed
good first issue
hacktoberfest
issue/bounty
issue/confirmed
issue/critical
issue/duplicate
issue/needs-feedback
issue/not-a-bug
issue/regression
issue/stale
issue/workaround
lgtm/need 2
modifies/api
modifies/translation
outdated/backport/v1.18
outdated/theme/markdown
outdated/theme/timetracker
performance/bigrepo
performance/cpu
performance/memory
performance/speed
pr/breaking
proposal/accepted
proposal/rejected
pr/wip
pull-request
Mirrored from GitHub Pull Request
 reviewed/wontfix
💰 Rewarded
skip-changelog
status/blocked
topic/accessibility
topic/api
topic/authentication
topic/build
topic/code-linting
topic/commit-signing
topic/content-rendering
topic/deployment
topic/distribution
topic/federation
topic/gitea-actions
topic/issues
topic/lfs
topic/mobile
topic/moderation
topic/packages
topic/pr
topic/projects
topic/repo
topic/repo-migration
topic/security
topic/theme
topic/ui
topic/ui-interaction
topic/ux
topic/webhooks
topic/wiki
type/bug
type/deprecation
type/docs
type/enhancement
type/feature
type/miscellaneous
type/proposal
type/question
type/refactoring
type/summary
type/testing
type/upstream
No Label type/docs type/proposal
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/gitea#3226
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?