Automate the generation of release change log draft #5712

daxian-dbw · 2017-12-18T18:36:55Z

PR Summary

Automate the generation of release change log draft.

For a commit that is breaking change, Get-ChangeLog assumes that a [breaking change] tag is put in the commit description body so that it can incorporate this information in the generated changelog entry.

So to @PowerShell/powershell-maintainers, please put the [breaking change] tag in the description body when you squash merge a PR that is a breaking change.

PR Checklist

Note: Please mark anything not applicable to this PR NA.

PR has a meaningful title
- Use the present tense and imperative mood when describing your changes
Summarized changes
[NA] User facing Documentation needed
- [NA] Issue filed - Issue link:
Change is not breaking
[NA] Make sure you've added a new test if existing tests do not effectively test the code changed
- [NA] Add [feature] if the change is significant or affectes feature tests
This PR is ready to merge and is not Work in Progress.
- If the PR is work in progress, please add the prefix WIP: to the beginning of the title and remove the prefix when the PR is ready.

TravisEz13 · 2017-12-18T18:56:57Z

tools/releaseTools.psm1

+        if ($commit.AuthorEmail.EndsWith("@microsoft.com")) {
+            $commit.ChangeLogMessage = "- {0}" -f $commit.Subject
+        } else {
+            $uri = "https://api.github.com/repos/PowerShell/PowerShell/commits/$($commit.Hash)"


This belongs better in this module: https://github.com/PowerShell/PowerShellForGitHub

That module is more about generic GitHub operations, while this one is specific to powershell. It's based on how we operate the repository, for example

we use squash merge almost all the time, so we can ignore merge commits when generating changelog.

our release process, including how we do cherry-picks and merge release branch to master.

the format of changelog entries, as well as the assumption that [breaking change] tag will be put in commit description body by maintainers.

You could also optimize this by getting the author email address locally and only going to github if you don't know the login for that email.

Good idea. We don't have to query GitHub for every commit from external contributors, as they may be from the same one. Here is an example of output:

- Replace Remaining HttpBin.org Tests with WebListener (#5665) (Thanks @markekraus!) - Combine Web Cmdlet Partial Class Files (#5612) (Thanks @markekraus!) - Enable conversions from PSMethod to Delegate (#5287) (Thanks @powercode!) - Fix PSVersion in PSSessionConfiguration tests (#5554) (Thanks @iSazonov!) - Update target tag for master CI to 6.1.0-preview.1 (#5513) - Remove AddTypeCommandBase class (#5407) (Thanks @iSazonov!)

We can save 2 queries in this example.

Added $community_login_map to cache the login names we queried.

iSazonov · 2017-12-18T19:02:38Z

tools/releaseTools.psm1

+##############################
+#.SYNOPSIS
+#In the release workflow, the release branch will be merged back to master after the release is done,
+#and a merge commit will be greated as the child of the release tag commit.


Typo greated -> treated .

Fixed. Thanks!

iSazonov · 2017-12-18T19:18:12Z

We have three places where we mark a breaking change - PR description, PR label and now commit description. Can we reduce this amount? Can we use the Breaking change PR label in the script?

TravisEz13

Please file issues, respond to or add todo comments for comments

daxian-dbw · 2017-12-18T20:00:16Z

@iSazonov IMHO, it's useful to keep the "breaking change" information in the commit. It also would force maintainers to edit the commit descirption body with better messages before merging (I think this is particularly necessary for a breaking change commit).

Today, we can easily find a commit whose body description is just a list of commit messages that are auto-generated by GitHub from the set of commits in the PR, including message entries like "* Address review comments" or "* Fix a test issue". Body descirption like this is not useful, so maintainers should edit the commit body description before merging a PR -- either remove all auto-generated messages when a body description is not needed, or replace with a summary that better describes the changes when a body description is needed. In case of a breaking change, a body description is necessary to describe the breaking change in summary, maybe even including why it's approved.

As for other places we mark for breaking change, they all have their purposes

Label in issue and PR. The label makes it easy to recognize the breaking change and easy to filter.
Checklist in PR description. It serves as a reminder to the maintainer assignee that the breaking change label needs to be added. Maybe this checklist is not absolutely necessary becuase the maintainer can look at the issue to know if it's a breaking change, but it makes it easier for the maintainer.

iSazonov · 2017-12-19T05:43:32Z

@daxian-dbw Thanks for clarify. I agree that keeping the breaking change label in commit description is useful.
Continuing to think about simplifying this process - can we assign a template to commit description in GitHub and/or Git?

Update: I see a community recommend to use git hooks:
https://stackoverflow.com/questions/14151775/how-do-i-set-a-pattern-for-git-commit-messages
https://stackoverflow.com/questions/13087625/git-gitolite-v3-pre-receive-hook-for-all-commit-messages
Update2: Maybe interesting
https://gist.github.com/stephenparish/9941e89d80e2bc58a153
https://www.npmjs.com/package/git-semantic-commits (https://github.com/russiann/git-semantic-commits)
http://karma-runner.github.io/1.0/dev/git-commit-msg.html -> sample http://karma-runner.github.io/1.0/about/changelog.html

daxian-dbw · 2017-12-19T18:37:00Z

@iSazonov Thank you for the research! Let me play with the hook.
I'm also planning to update the maintainer README.md about the commit message requirement.

iSazonov · 2017-12-19T18:40:31Z

@daxian-dbw If you plan to play with Git hooks please take attention on #3504 too.

daxian-dbw · 2017-12-19T18:41:41Z

@iSazonov Will do, thanks!

TravisEz13 · 2017-12-19T23:24:41Z

We should investigate what git hooks can do for us, but I cannot find any docs that GitHub supports these. I doubt that these would be supported as it would allow fairly arbitrary code to run on GitHub's servers.

iSazonov · 2017-12-20T09:37:50Z

@TravisEz13 Good news (although preview only) https://developer.github.com/v3/enterprise-admin/pre_receive_hooks/
Another way is GitHub Webhooks https://developer.github.com/v3/orgs/hooks/

Create the module 'releaseTools.psm1' under 'tools' folder, which expose the function 'Get-ChangeLog' to generate a release change log based on the local commit history.

daxian-dbw added 3 commits December 17, 2017 17:18

Automate the generation of ChangeLog

74c8605

Rename the module to 'releaseTools.psm1'

f442cea

Add more comments

a39f77a

daxian-dbw self-assigned this Dec 18, 2017

daxian-dbw requested review from TravisEz13, adityapatwardhan and anmenaga December 18, 2017 18:36

Add the prefix '-' to changelog entries

29aaa9b

TravisEz13 reviewed Dec 18, 2017

View reviewed changes

iSazonov reviewed Dec 18, 2017

View reviewed changes

TravisEz13 approved these changes Dec 18, 2017

View reviewed changes

Address comments

0fa993b

TravisEz13 approved these changes Dec 18, 2017

View reviewed changes

iSazonov approved these changes Dec 19, 2017

View reviewed changes

Only expose the function 'Get-ChangeLog'

3c09ff0

daxian-dbw merged commit c17a975 into PowerShell:master Dec 19, 2017

daxian-dbw deleted the changelog branch December 19, 2017 21:39

TravisEz13 added this to the 6.0.0-GA milestone Dec 20, 2017

TravisEz13 mentioned this pull request Dec 21, 2017

Merge 6.0.0 ga changes #5729

Merged

TravisEz13 mentioned this pull request Apr 14, 2018

Changelog generation automation #5614

Closed

Automate the generation of release change log draft #5712

Automate the generation of release change log draft #5712

Uh oh!

Conversation

daxian-dbw commented Dec 18, 2017

PR Summary

PR Checklist

Uh oh!

TravisEz13 Dec 18, 2017

Choose a reason for hiding this comment

Uh oh!

daxian-dbw Dec 18, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TravisEz13 Dec 18, 2017

Choose a reason for hiding this comment

Uh oh!

daxian-dbw Dec 18, 2017

Choose a reason for hiding this comment

Uh oh!

daxian-dbw Dec 18, 2017

Choose a reason for hiding this comment

Uh oh!

iSazonov Dec 18, 2017

Choose a reason for hiding this comment

Uh oh!

daxian-dbw Dec 18, 2017

Choose a reason for hiding this comment

Uh oh!

iSazonov commented Dec 18, 2017

Uh oh!

TravisEz13 left a comment

Choose a reason for hiding this comment

Uh oh!

daxian-dbw commented Dec 18, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iSazonov commented Dec 19, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

daxian-dbw commented Dec 19, 2017

Uh oh!

iSazonov commented Dec 19, 2017

Uh oh!

daxian-dbw commented Dec 19, 2017

Uh oh!

TravisEz13 commented Dec 19, 2017

Uh oh!

iSazonov commented Dec 20, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

daxian-dbw Dec 18, 2017 •

edited

Loading

daxian-dbw commented Dec 18, 2017 •

edited

Loading

iSazonov commented Dec 19, 2017 •

edited

Loading