Add documentation and tests for label changelog label section assignment behavior #822

bnigh · 2019-12-19T22:25:18Z

What Changed

Took attempt at updating label config docs to better communicate (a) default labels & (b) how PRs are assigned to a label section
Added a few tests for changelog / releaseNote generation to check for documented behavior

Why

To improve accessibility of new auto users to understand what the default changelog / release notes will look like and how they might modify the config to achieve desired customization
See this comment

Todo:

Add tests
Add docs

Callouts

I'm not 100% liking the way the changes to the docs turned out so far... but wanted to create a PR to get feedback / start the conversation of how to best improve the existing docs

Published PR with canary version:

Published under canary scope @auto-canary

@auto-canary/auto@8.7.3-canary.822.10958.0
@auto-canary/core@8.7.3-canary.822.10958.0
@auto-canary/all-contributors@8.7.3-canary.822.10958.0
@auto-canary/chrome@8.7.3-canary.822.10958.0
@auto-canary/conventional-commits@8.7.3-canary.822.10958.0
@auto-canary/crates@8.7.3-canary.822.10958.0
@auto-canary/first-time-contributor@8.7.3-canary.822.10958.0
@auto-canary/git-tag@8.7.3-canary.822.10958.0
@auto-canary/jira@8.7.3-canary.822.10958.0
@auto-canary/maven@8.7.3-canary.822.10958.0
@auto-canary/npm@8.7.3-canary.822.10958.0
@auto-canary/omit-commits@8.7.3-canary.822.10958.0
@auto-canary/omit-release-notes@8.7.3-canary.822.10958.0
@auto-canary/released@8.7.3-canary.822.10958.0
@auto-canary/s3@8.7.3-canary.822.10958.0
@auto-canary/slack@8.7.3-canary.822.10958.0
@auto-canary/twitter@8.7.3-canary.822.10958.0
@auto-canary/upload-assets@8.7.3-canary.822.10958.0

…tion

…g-labels

codecov · 2019-12-19T22:34:54Z

Codecov Report

Merging #822 into master will increase coverage by 0.07%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #822      +/-   ##
==========================================
+ Coverage   85.39%   85.47%   +0.07%     
==========================================
  Files          36       36              
  Lines        2404     2402       -2     
  Branches      337      309      -28     
==========================================
  Hits         2053     2053              
+ Misses        274      272       -2     
  Partials       77       77

Impacted Files	Coverage Δ
packages/core/src/auto.ts	`85.46% <0%> (+0.37%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a915ba1...0d286f9. Read the comment docs.

hipstersmoothie

Great additions to the docs ❤️

hipstersmoothie · 2019-12-19T22:40:53Z

docs/pages/autorc.md

+<details><summary>Click here to see the default label configuration</summary>
+
+```json
+[


This is a great addition!

hipstersmoothie · 2019-12-19T22:44:55Z

docs/pages/autorc.md

 #### Changelog Titles

-By default auto will create sections in the changelog for the following labels.
+Each PR included in the release will be matched to the first label defined in the config with a `changelogTitle` in priority order of the `releaseType` (major, minor, patch, then all others) and included as an entry within that section


Suggested change

Each PR included in the release will be matched to the first label defined in the config with a `changelogTitle` in priority order of the `releaseType` (major, minor, patch, then all others) and included as an entry within that section

Each PR included in the release will be matched to the first label defined in the config with a `changelogTitle`.

All matching commits are grouped together and rendered as one section in the changelog.

Sections are in priority order based on the `releaseType` (`major`, `minor`, `patch, then all others).

@hipstersmoothie
I agree that the wording can be improved...

One piece of info that we may lose by removing that wording is the following scenario:

my config

{ "labels": [ { "releaseType": "none", "name": "foo", "changelogTitle": "Foo" }, { "releaseType": "minor", "name": "bar", "changelogTitle": "Bar" } ] }

if a PR has both foo and bar labels, then technically, the first label in the config is foo, but the PR would be assigned to the bar section.

This likely will not be a common use case, but wondering if it is worth keeping the info in the docs in a different format for completeness.

What are your thoughts?

@hipstersmoothie

Ah I see. I just wanted to break up the sentence a little bit. I agree with
you we should keep the original wording maybe a little clearer

Definitely open to suggestions about how to improve the wording.

How about rewording to something like below?

Changelog Titles

Each PR included in the release will be assigned to a label section based upon the matching label with the highest releaseType that has a changelogTitle.

Priority order of releaseType from highest to lowest: major, minor, patch, and then all others

If a PR has multiple labels of the same releaseType, then the PR is assigned based upon the label that is assigned first in the config

By default auto will create sections in the changelog for the following labels:

major

minor

patch

internal

documentation

For example:

Using the default config, if a given PR has the labels minor and internal, then it will be included in the minor label section

Using the default config, if a given PR has the labels documentation and internal, then it will be included in the internal label section

should be addressed in: 0d286f9

hipstersmoothie · 2019-12-19T22:46:38Z

packages/core/src/__tests__/changelog.test.ts

@@ -200,6 +199,78 @@ describe('generateReleaseNotes', () => {
    expect(await changelog.generateReleaseNotes(normalized)).toMatchSnapshot();
  });

+  test('should prefer section with highest releaseType for PR with multiple labels', async () => {


I like that you used test to validate how it works for your docs! Awesome

hipstersmoothie · 2019-12-20T02:39:51Z

Ah I see. I just wanted to break up the sentence a little bit. I agree with you we should keep the original wording maybe a little clearer

…

On Thu, Dec 19, 2019 at 3:05 PM bnigh ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/pages/autorc.md <#822 (comment)>: > #### Changelog Titles -By default auto will create sections in the changelog for the following labels. +Each PR included in the release will be matched to the first label defined in the config with a `changelogTitle` in priority order of the `releaseType` (major, minor, patch, then all others) and included as an entry within that section @hipstersmoothie <https://github.com/hipstersmoothie> I agree that the wording can be improved... One piece of info that we may lose by removing that wording is the following scenario: my config { "labels": [ { "releaseType": "none", "name": "foo", "changelogTitle": "Foo" }, { "releaseType": "minor", "name": "bar", "changelogTitle": "Bar" } ] } if a PR has both foo and bar labels, then technically, the first label in the config is foo, but the PR would be assigned to the bar section. This likely will not be a common use case, but wondering if it is worth keeping the info in the docs in a different format for completeness. What are your thoughts? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#822?email_source=notifications&email_token=AAJDEBFP5LO33EQLWEOKR73QZP4Z3A5CNFSM4J5RUJVKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCP3YMUY#discussion_r360161546>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJDEBCZSFTIIIZ4UXADJKLQZP4Z3ANCNFSM4J5RUJVA> .

adierkens · 2020-01-02T17:20:35Z

🚀 PR was released in v8.8.0 🚀

bnigh added 4 commits December 19, 2019 13:14

Update label config docs to include denote how a PR is added to a sec…

a18a6c9

…tion

Merge remote-tracking branch 'upstream/master' into document-changelo…

3794536

…g-labels

Add tests to verify changelog section assignment behavior

874da74

Update existing test so behavior matches name

a39076b

hipstersmoothie approved these changes Dec 19, 2019

View reviewed changes

Refactor docs based upon review comments

0d286f9

hipstersmoothie added the documentation Changes only affect the documentation label Dec 22, 2019

hipstersmoothie merged commit 97cff20 into intuit:master Dec 22, 2019

adierkens added the released This issue/pull request has been released. label Jan 2, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation and tests for label changelog label section assignment behavior #822

Add documentation and tests for label changelog label section assignment behavior #822

bnigh commented Dec 19, 2019 •

edited by adierkens

codecov bot commented Dec 19, 2019 •

edited

hipstersmoothie left a comment

hipstersmoothie Dec 19, 2019

hipstersmoothie Dec 19, 2019

bnigh Dec 19, 2019

bnigh Dec 20, 2019 •

edited

hipstersmoothie Dec 20, 2019

bnigh Dec 20, 2019

hipstersmoothie Dec 19, 2019

hipstersmoothie commented Dec 20, 2019 via email

adierkens commented Jan 2, 2020

-Each PR included in the release will be matched to the first label defined in the config with a `changelogTitle` in priority order of the `releaseType` (major, minor, patch, then all others) and included as an entry within that section
+Each PR included in the release will be matched to the first label defined in the config with a `changelogTitle`.
+All matching commits are grouped together and rendered as one section in the changelog.
+Sections are in priority order based on the `releaseType` (`major`, `minor`, `patch, then all others).

Add documentation and tests for label changelog label section assignment behavior #822

Add documentation and tests for label changelog label section assignment behavior #822

Conversation

bnigh commented Dec 19, 2019 • edited by adierkens

What Changed

Why

Todo:

Callouts

codecov bot commented Dec 19, 2019 • edited

Codecov Report

hipstersmoothie left a comment

Choose a reason for hiding this comment

hipstersmoothie Dec 19, 2019

Choose a reason for hiding this comment

hipstersmoothie Dec 19, 2019

Choose a reason for hiding this comment

bnigh Dec 19, 2019

Choose a reason for hiding this comment

bnigh Dec 20, 2019 • edited

Choose a reason for hiding this comment

Changelog Titles

hipstersmoothie Dec 20, 2019

Choose a reason for hiding this comment

bnigh Dec 20, 2019

Choose a reason for hiding this comment

hipstersmoothie Dec 19, 2019

Choose a reason for hiding this comment

hipstersmoothie commented Dec 20, 2019 via email

adierkens commented Jan 2, 2020

bnigh commented Dec 19, 2019 •

edited by adierkens

codecov bot commented Dec 19, 2019 •

edited

bnigh Dec 20, 2019 •

edited