search

go-gitea / gitea

Git with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD
https://gitea.com
MIT License
44.71k stars 5.46k forks source link

New approach to changelog management #6711

Closed jolheiser closed 1 year ago

jolheiser commented 5 years ago

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 commented 5 years ago

@go-gitea/maintainers pinging for feedback.

techknowlogick commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

guillep2k commented 4 years ago

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:

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 commented 4 years ago

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

jolheiser commented 4 years ago

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 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 4 years ago

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

jolheiser commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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

bkcsoft commented 4 years ago

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:

lunny commented 1 year ago

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.