Gitea: New approach to changelog management

[jolheiser]

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.

[jolheiser]

@go-gitea/maintainers pinging for feedback.

[techknowlogick]

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.

[MarkusAmshove]

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

[lunny]

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

[guillep2k]

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.

[jolheiser]

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

[jolheiser]

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

[jolheiser]

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.

[guillep2k]

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.

[jolheiser]

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

[guillep2k]

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

[lafriks]

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

[sapk]

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.

[lunny]

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]

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

[jolheiser]

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:

[lunny]

@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. 😄

[jolheiser]

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

[bkcsoft]

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: