Repository: angular
Issue: ci: improve changelog generation tooling
Labels: area: build & ci,area: dev-infra,P3

While working on #39704, I noticed some potential improvements to our changelog generation tooling. This issue is for discussing/tracking them.


## Potential fixes

- **Summary:** Do not include any URL and issue/PR reference to the "closes" section.
  **Example:** https://github.com/angular/angular/pull/39704/commits/dd3cf854e13c33cfc6d5771c78ffe62e626df2c7
  **Description:**  
  Currently, the tooling seems to "think" that any URL or issue/PR reference found in the commit message refers to a GitHub issue. As a result, it adds it to the changelog in the list of issues closed by the commit.

- **Summary:** Include link to corresponding commit for each breaking change.
  **Example:** https://github.com/angular/angular/pull/39704/commits/222643108c39f45e8a930a43f3e9f1241e9fa817
  **Description:**  
  Looking at the commit that introduces a breaking change makes it much easier to understand the full implications and how to handle it. By adding a link to commit that introduced the breaking change in the "Breaking changes" section of a release, the user is able to easily get to the full commit message (which might contain useful context) and the actual code changes associated with the breaking change.

- **Summary:** Use the full commit SHA when generating links to commits.
  **Example:** https://github.com/angular/angular/pull/39704/commits/2085e754f7ff5437e4198db5d11d38ecad4f407b
  **Description:**  
  Currently, the tooling uses the first few characters of a commit SHA to generate the URL used to link to a commit (for example `https://github.com/angular/angular/commit/a1b2c3d`). Such URLs work fine on GitHub as long as there is no other commit in the repo (or forks of the repo afaict) that start with the same characters. If there is another commit (now or in the future), such URLs will return a 404 page.  
  To avoid this issue, the tooling should use the full SHA of the commit (40 characters) for generating the URL. It can still use fewer characters for the link text, so the rendered Markdown is shorter, for example:  
`[a1b2c3d](https://github.com/angular/angular/commit/a1b2c3d4e5f6g7h8i9j0a0b9c8d7e6f5g4h3i2j1)`


## Potential improvements

- **Summary:** Improve how linked commits/issues/PRs are presented.
  **Example:**  
  ```diff
  -**scope:** commit summary (#38681) (6ae3b68), closes #38596, #69583
  +**scope:** commit summary (6ae3b68 | PR #38681 | closes #38596, #69583)
  ```
  **Description:** 
  Currently, the commit and PR associated with the commit as well as the issues/PRs closed by the commit are presented in the following format:  
  `**<scope>:** <commit summary> (<PR>) (<commit>), closes <issue-1>, <issue-2>`

  This looks inconsistent and potentially confusing: Having the first two (the commit SHA and the PR) parenthesized (but in different sets of parenthesis) and separated by spaces, followed by the closed issues which are unparenthesized and separated by a comma.

  I suggest presenting this info in a more consistent way, such as:  
  `**<scope>:** <commit summary> (<commit> | PR <PR> | closes <issue-1>, <issue-2>)`
  ...or...
  `**<scope>:** <commit summary> (<commit>, <PR>, closes <issue-1> <issue-2>)`

  For reference, these are presented in a similar way in the [AngularJS changelog](https://github.com/angular/angular.js/blob/master/CHANGELOG.md):  
  `**<scope>:** <commit summary> (<commit>, <PR>, <issue-1>, <issue-2>)`  

- **Summary:** Capitalize the first letter of the commit summary.
  **Example:** https://github.com/angular/angular/pull/39704/commits/540c65640b9b7dfc4ec6b91f1b7055fbbd9118ef (among other changes in that commit)
  **Description:**  
  Currently, we keep the capitalization of each commit message summary, resulting in inconsistent capitalization:  
  ```markdown
  - **scope1:** some change
  - **scope2:** Another change
  ```

  It would be better to have consistent capitalization.

  NOTE: According to our [commit message guidelines](https://github.com/angular/angular/blob/d68cac69ed072f9aa98dbd8982f849b9810fc071/CONTRIBUTING.md#commit-message-header), the summary should _not_ be capitalized. However, we do not enforce this, which results in mixed capitalization. We could consider either enforcing it (in our commit message validation) or removing the guideline.

- **Summary:** Make bulleted lists with changes for each scope.
  **Example:** https://github.com/angular/angular/pull/39704/commits/222643108c39f45e8a930a43f3e9f1241e9fa817 (This commit does it for the "Breaking Changes" section, but we can do it to all sections.)
  **Description:**  
  Currently, the scope of each commit is included in the corresponding entry in the changelog. This applies to all sections ("Bug Fixes", "Features", "Breaking Changes", etc.). Example:
  ```markdown
  - **compiler:** Fix this.
  - **compiler** Add that.
  - **compiler-cli:** Add this.
  - **compiler-cli:** Add that.
  ```

  Since commits are grouped by scope, the separation would become clearer if we created a bulleted list of each scope. The example above would become:
  ```markdown
  - **compiler:**
    - Fix this.
    - Add that.
  - **compiler-cli:**
    - Add this.
    - Add that.
  ```

  For reference, this is how it was done in the AngularJS changelog. See, for example, the [AngularJS 1.7.0 changelog](https://github.com/angular/angular.js/blob/master/CHANGELOG.md#170-nonexistent-physiology-2018-05-11).