Automate the generation of release notes

[nannanli]

Is your request for enhancement related to a problem? Please describe.

The generation of release notes is an error-prone manual process now to track changes in multiple repos and add related PR or issue number to each entry.

Describe the solution you'd like

Set up PR closing template in relevant repos as input. Then automate the generation of release notes. The output may look like this. Note that moved the PR and issue numbers to the end for there is possibility that multiple PRs fix the same issue and the following layout makes the content more readable.

# Features and enhancements
## API Mediation Layer
- PR description [PR#122] (Issue #101) (Docs)
- PR description [PR#123] (Issue #102) (Docs)
......
# Bug fixes
## API Mediation Layer
- PR description [PR#124] (Issue #103) (Docs)
- PR description [PR#125] (Issue #104) (Docs)

Related doc pages

https://docs.zowe.org/stable/getting-started/summaryofchanges.html#version-1-7-0-november-2019

Additional context

See a sample PR closing template as follows> It's running in the zowe-install-packaging repo now.
https://github.com/zowe/zowe-install-packaging/blob/master/.github/pull_request_template.md

[nannanli]

For convenience, the PR template details are as follows. Open for feedback and comments now. We want to set it up in some relevant repos for pilot run before we move to the ZLC and promote it to the broader community.

---

Please check if your PR fulfills the following requirements. This is simply a reminder of what we are going to look for before merging your PR. If you don't know all of this information when you create this PR, don't worry. You can edit this template as you're working on it.

• Tests for the changes have been added (for bug fixes / features)
• Necessary documentation (if appropriate) have been added / updated
• DCO signoffs have been added to all commits, including this PR

PR type

What type of changes does your PR introduce to Zowe? Put an x in the box that applies to this PR. If you're unsure about any of them, don't hesitate to ask.

• Bugfix
• Feature
• Other... Please describe:

Relevant issues

Fixes

Changes proposed in this PR

Does this PR introduce a breaking change?

• Yes
• No

Does this PR do something the person installing Zowe should know about?

---

• Affected function: general area of interest *

---

• Description: 1 line description *

---

• Part: name of customizable file involved *

---

multi-line description

Is there a related doc issue or Pull Request?

Doc issue/PR number:

Other information

---

[nannanli]

Initial comments from the doc squad:

• Need to make it clear that if people do not provide some required information in this template when closing the PR, there won't be a release notes entry in docs.
• Need to make it clear what's required, what's optional. For example, there might not be a doc issue for this PR.

@BrandonJenkins14 @JamesBauman @jasonenglish2039 @janan07 Box has access issue so I'm posting it here.

[BrandonJenkins14]

@zFernand0 @MarkAckert We would appreciate any feedback that you might have on this Pull Request template for Zowe. The goal is to automate the generation of Zowe Release Notes rather than manually gathering them at release time.

[jasonenglish2039]

@NolanRogers @1000TurquoisePogs, see pull request template proposal.

[NolanRogers]

@DivergentEuropeans @timgerstel @sakeerthy @DmitryNikolaev @struga0258 @jordanCain @NakulManchanda . Hello Team, can you guys please review this?

[zFernand0]

For convenience, the PR template details are as follows. Open for feedback and comments now. We want to set it up in some relevant repos for pilot run before we move to the ZLC and promote it to the broader community.

I understand and agree with the proposal of pushing it out to some relevant/key repos to try it out. However, I believe the ZLC may need to be involved a little sooner because of the DCO sign-offs.
I do see that it's on the checklist of things to do before a PR can be accepted though, but DCOs may be of less value depending on the next steps (for example, if PRs get squashed).

I believe that having a template in general is a good starting point. and also having a standard merge-commit at PR closing (hopefully conventional commits will greatly help the people automating the creation and updates of the release notes : )

[nannanli]

A proposal of unifying the CHANGELOG format as a basis for the release notes automation.
Zowe CHANEGELOG and release notes(1).docx

[PeterFandelAtRocket]

HI Ashley, I agree with all your proposals in the doc file in previous comment and the App Framework squad has recently been moving in that direction. I would propose an additional change at the "Notable Changes" level. I am not sure if there is a set process for writing the notable changes section but it seems, reading last few releases, that it does not consistently summarize what is notable across all squads.

[BrandonJenkins14]

@PeterFandelAtRocket That's a fair point.

In 1.13.0, the CLI squad felt that a particular Zowe CLI feature should be advertised more prominantly than some more minor enhancements, so we created this Notable Changes section. I encourage each squad to "advertise" their most significant changes in this section. We definitely want equal representation for any component in the future!

For automation, I suppose we could have a notable_feature tag on pull requests, or developers could add "Notable:" to their changelog entry.

Maybe this part should still be manual, though. Writers can work with their teams to decide what features are most notable, and write about them accordingly?

[nannanli]

@PeterFandelAtRocket Hi Peter, thanks for the updates and proposal! As @BrandonJenkins14 mentioned, v1.13 is the first release we started the "Notable Changes" information where we explain in details some highlighted features or enhancements including their value and the impact on user behavior, etc. This kind of information is too heavy for CHANGELOG so I think it will remain a manual process in the future. Moving forward and in the upcoming v1.14 release, we'll ensure that each squad adds notable changes to consistently do this. Writers from the doc squad will also work with squads to review and edit the information.

[1000TurquoisePogs]

Include an issue or PR number for each entry. This helps users learn more about the change when needed.

This is a little annoying to do since the PR contains the change, but you make the PR after you write the doc, so you need to effectively write the doc, submit the PR, then edit the doc again and update the PR. There must be a better way?

Indicate whether the change is a new feature/enhancement or a bug fix. This helps users understand quickly what new enhancements are introduced and decide whether to upgrade.

I would like to go one step beyond this. Some people have questioned the significance and relevance of some changelog items. To them I was saying that they weren't the target audience, because there's more than one target audience for our changelog: Developers, Users, Administrators
I think changelog items should signify which audience should care about it.
This can be easy to do,

• Updated the port validation logic to reduce false negatives. Zowe icon in the tab for the docs site #1399
  Could become
• [D][A] Updated the port validation logic to reduce false negatives. Zowe icon in the tab for the docs site #1399
  This is relevant to [D]evelopers and [A]dmins, but I don't think [U]sers will notice the difference.