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.