Automatic generation of release notes

[dawidgora]

Similar to GitHub, release notes can now be generated automatically.
The generator is server-side and gathers the merged PRs and contributors and returns the corresponding Markdown text.

Screenshots

[wxiaoguang]

Also cc @techknowlogick for further review and help (#35976 (comment)) , in case you already have more discussions.

[dawidgora]

In 1406ccc:

• Added helpers so release notes pick the release immediately before the one being edited, not just the latest one
• This avoids errors when updating notes on older releases because we now compare against the correct predecessor tag.

[dawidgora]

In followup PR, when I find some time I will implement additional configuration for this feature, like it is on GitHub: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

[wxiaoguang]

Too many unnecessary if and ? for "defensive programming"
Most of them should be removed. If you write a if or ? , then you should clearly know that in which case it can happen.

Still many if and ? in code that I don't understand.

---

And #35977 (comment)

Also cc techknowlogick for further review and help (#35976 (comment)) , in case you already have more discussions.

[dawidgora]

Too many unnecessary if and ? for "defensive programming"
Most of them should be removed. If you write a if or ? , then you should clearly know that in which case it can happen.

Still many if and ? in code that I don't understand.

Ok, I made it less defensive now @wxiaoguang

And #35977 (comment)

Also cc techknowlogick for further review and help (#35976 (comment)) , in case you already have more discussions.

We haven't, but @techknowlogick feel free to review my PR

[wxiaoguang]

TBH, still questions (only a quick look, not carefully look into backend code yet)

[wxiaoguang]

A UX problem:

If user has input many message in the textarea, then click the "Generate release notes" button, then their work is lost and no way to undo?

Is it better to "append" but not "replace"?

[wxiaoguang]

Should it support tag name with fields? For example: releases/v1.0

[dawidgora]

Yeah, good idea. What would you say if, in such a case, it needed to match the same field as the currently created tag?

For example, if we are creating a new release with the tag release/v1.1.0, it would look for release/v1.0.0, but not for nightly/1.0.0.

Or maybe it’s overengineering, and we should keep it simple. Let me know how you see it, and I can adjust the logic.

[wxiaoguang]

Maybe we should remove the "Auto" feature, and always let end users choose?

We can make a best guess (only compare the last field) to make the latest tag to be selected by default on the UI. It could also simplify the code.

And users can clearly know what would happen

[dawidgora]

Ok, I'll do it like this. I hope to find some time today, but can't promise

[dawidgora]

Okay, I see. I assume it currently collects commits. In the future, we could consider adding an option to collect either commits or pull requests.

It's practically useless to me when it does not include commits without a associated pull request, as I think that's a very common scenario, for example when the repo owner does fixups etc.

But if it matches GH (it seems so), I won't block on it.

I can implement that in the following PR, along with other improvements. But first, I'd like to have this one merged.

[silverwind]

Okay, I see. I assume it currently collects commits. In the future, we could consider adding an option to collect either commits or pull requests.

It's practically useless to me when it does not include commits without a associated pull request, as I think that's a very common scenario, for example when the repo owner does fixups etc.
But if it matches GH (it seems so), I won't block on it.

I can implement that in the following PR, along with other improvements. But first, I'd like to have this one merged.

Fine with me.

[silverwind]

Branch needs to be updated and it will likely have some new typescript issues because we enabled strictNullChecks in #35843.

[wxiaoguang]

A UX problem:

If user has input many message in the textarea, then click the "Generate release notes" button, then their work is lost and no way to undo?

Is it better to "append" but not "replace"?

Just tested with GitHub, it "resolves" this problem by disabling the generation when the textarea is not empty:

Details

ps: GitHub has more logic for the "generation", I didn't mean that we must follow GitHub, while I think at least we should avoid surprising end users. Maybe using a modal dialog is better, then the UI can be simplified and more options can be added in the future (for example: add a checkbox to also add commit messages without a PR)

[wxiaoguang]

Now a new question about "new tag without previous tag"

Details

func findInitialCommit(commit *git.Commit) (*git.Commit, error) {
	// FIXME: this method is inefficient for large repos with long histories, and it doesn't seem right:
	// FIXME: "git diff aaaa...bbbb" doesn't include commits from "aaaa", so the changes in "root commit" won't appear in the tag release's diff.
	// No idea whether we should really make things so complicated.

GitHub:

[wxiaoguang]

Made some new changes and addressed the concerns above (by my understanding).

New changes

• Fix various UI problems
  • Automatic generation of release notes #35977 (comment)
  • And many others (including legacy UI problems, misalignments, unclear prompts, mobile layout, etc)
• Don't overwrite the user inputted content when generating
  • Automatic generation of release notes #35977 (comment)
  • Automatic generation of release notes #35977 (comment)
• Also support prefixes like "release/v1.2.3"
  • Automatic generation of release notes #35977 (comment)
• Use a modal dialog for the "generate release notes" operation, then we can have more spaces to put more options in the future.
  • Automatic generation of release notes #35977 (comment)
• Don't iterate to the first commit for a new tag which doesn't have a previous tag, use "/{owner}/{repo}/commits/tag/{tag-name}" for the "change log link". This is also what GitHub does, I think it makes more sense.
  • Automatic generation of release notes #35977 (comment)
• Remove the "Auto" option, we do the best guess to select the previous tag, then users can clearly know that which tag will be used for the previous tag
  • Automatic generation of release notes #35977 (comment)

---

New screenshots

Details

[dawidgora]

Thank you for wrapping it up @wxiaoguang, I was busy lately.. One thing: I don't think moving previous tag selections saves any space. UX was better without modal IMO

[wxiaoguang]

One thing: I don't think moving previous tag selections saves any space. UX was better without modal IMO

IMO the new layout seems better and clearer (ps: I think it does save some space because we don't need to put a 38px height dropdown there, now we only have a tiny button, it's also easier for mobile layout)

And there are more reasons for why a modal does better in my mind:

• The elements in the form are usually related to the form and will be submitted. If we put the "previous tag" selector in the "release note form", it looks strange because the selector's value isn't for the form.
• Putting "previous tag" in the form (like GitHub) makes the logic much more complex than it should be. I have tested GitHub's release edit page, it sometimes hides something, sometimes disables something, and it needs to sync the states for different inputs. Overall the GitHub's design looks not good to me.

When using a modal for "generate release notes", the logic is clearer than before:

• The "previous tag" won't be displayed in the form, then it won't mislead users.
• The user first chooses a target tag, then use the modal to choose a previous tag. When the modal is open (just one more click), the target tag is determined, then not like GitHub which does a lot of tricks to sync the states.
• We don't need to use "auto" anymore since the target tag is determined, users can clearly know which tag will be used for previous tag: a determined behavior.
• The code can be simplified, less code, fewer bugs :)

So the modal dialog seems to be the best choice at the moment in my mind, while I am also open for other better solutions.

---

Old	New

[dawidgora]

Fair enough. Is there anything else here left to do?

[wxiaoguang]

Is there anything else here left to do?

No from my side. Maybe we can leave it open for some time in case other maintainers would have suggestions.

If nothing more to change, I think we can get it merged in one or two days.

Thank you very much for this awesome feature!