[RFC] Simplify label configuration

[zephraph]

Is your feature request related to a problem? Please describe.

Throughout the process of working on autobot I've struggled with handling/parsing/groking auto's label configuration setup.

Even when I started using auto, mapping the behavior of what I wanted to the available configuration was a little tricky.

Below I'll outline some of the behavior I think makes it more complex than it needs to be:

• Label definitions can be a string or an object. This helps for shorthand, but makes it a little harder to mentally map (and build tooling for). Objects can have a name, but it's optional (pulling from the key if it's not defined). This makes tooling a bit harder.
• There's labels and skipReleaseLabels. A label in labels that's also in skipReleaseLabels will skip a release. So if you want a documentation label that doesn't do a release, it needs to be added in two places. Also, what happens when you add major, minor, or patch to the skipReleaseLabels section? And then there's the skip-release label which is different from the skipReleaseLabels.
• Changelog titles can be added to labels, but it's not exactly clear in what order they take precedent. If minor and documentation labels both exist, which changelog title takes precedent?

Describe the solution you'd like

I'd like to propose that we vastly simplify the label definition and clearly document any corner cases. This is just one suggestion.

{
  labels: [
    {
      name: 'Breaking change',
	  releaseType: 'major',
      description: 'A non-backwards compatible change'
      changelogTitle: 'Breaking changes',
      color: '#FFF000'
    },
    {
	  name: 'Feature',
      releaseType: 'minor',
      description: 'A new capability'
      changelogTitle: 'Improvements',
      color: '#FAA00A'
    }, 
    {
	  name: 'Bug fix',
      releaseType: 'patch',
      description: 'A bug fix'
      changelogTitle: 'Bug fixes',
      color: '#FAA00A'
    },
    {
 	  name: 'Skip Release',
      releaseType: 'skip',
      description: "Ensures a release doesn't happen",
      // changelog title not valid for skip releases
      // changelogTitle: '',
      color: '#FAA00A'
	},
    {
      name: 'Documentation',
      releaseType: 'none',
      description: 'Used to denote documentation changes',
      changelogTitle: 'Documentation updates',
      color: '#C8C8C8'
    }
  ]
}

Logic

• name and releaseType are required
• releaseType is defined as major | minor | patch | skip | none. This can be further reduced to three categories: semver | skip | none.
• Only a single semver label can be present at any one given time.
• A semver label must be present, unless a none is otherwise present.
• A skip label is only valid when paired with a semver label and is otherwise a no-op.
• A none type generates no release by itself, but can be included with a semver label to include an extra changelog entry.
• A none release does not cause a release to be skipped if a semver label is present.
• Multiple none labels can be included to add the PR under different sections of the changelog
• In this proposal there's no such thing as an arbitrary label. Any label included has some impact on the release.

Describe alternatives you've considered

This is admittedly still complicated and certainly more verbose. An alternative (and a slight compromise to what we have today) would be to treat the semver labels differently.

{
  labels: {
    major: "Version: Major",
    minor: {
      name: "Version: Minor",
      changelogTitle: "Bug fixes"
    },
    patch: "Version: Patch",
    other: [
      {
        name: 'Skip release',
        skipRelease: true
      },
      {
        name: 'Documentation',
        changelogTitle: 'Documentation updates'
      }
    ]
  }
}

In this version, major, minor, and patch keep a similar api to what they have today. They're essentially treated as special cases though. All other labels go into this other bucket (which could have a better name).

In this scenario:

• only a single semver can be present at a time
• skipRelease: true can be included on other labels to make them a skip.
• changelogTitle can be included on other labels to add a changelog entry. (Again, this would be duplicative of other entries).
• Having neither skipRelease or changelogTitle would make the label a no-op arbitrary label (which preserves the arbitrary label support we have today).

---

Ultimately I'm open to other ideas. I just think our current approach is pretty rife with undocumented corner cases and gotchas. I'd like to make this as easy to understand (and to code for) as possible.

[hipstersmoothie]

I like the first option. it is a super simple and clean, I'm having trouble picking apart the difference between none and skip. If i understand correctly skip has no bearing on the changelog and needs to be with a semver label, and none will skip a release but create a unique changelog entry.

[hipstersmoothie]

this method gets rid of most of the shorthands but i think we could still support a few?

for instance the following would override the default major label but also inherit the description and changelogTitle

{
  labels: [
    {
      name: 'Breaking change',
      releaseType: 'major'
    }
  ]
}

or just editing the title

{
  labels: [
    {
      releaseType: 'major',
      changelogTitle: 'Super Big Changes'
    }
  ]
}

[zephraph]

skip is don't do a release. none means that the label has no effect on the release... so it may release or it may not release, depending on the presence of other labels. It does need a better name.

So under your suggestion, the labels have default fallbacks based on what releaseType is present? I think that makes sense.

[hipstersmoothie]

So under your suggestion, the labels have default fallbacks based on what releaseType is present? I think that makes sense.

yeah

[tunnckoCore]

@zephraph It does need a better name.

I think it's a great one. There's nothing more better than saying "it's none because it has none impact on the release process, eg. chore/dependencies/whatever".

think that makes sense.

Yeap, totally.

The proposal is awesome.
I think that name and chagelogTitle should both have defaults based on the releaseType.

[hipstersmoothie]

I have a PR up for this now. It does not address the following

1. Changelog titles can be added to labels, but it's not exactly clear in what order they take precedent. If minor and documentation labels both exist, which changelog title takes precedent?

2. Logic most of the validation described here should probably live in autobot. I dont think auto itself should be onforcing this

3. (related to 1) > Multiple none labels can be included to add the PR under different sections of the changelog

[tunnckoCore]

I don't get it. How "A skip label is only valid when paired with a semver label and is otherwise a no-op." make sense? If i have deps label or infra, type is skip and I want to skip releasing why I need to add semver label too? I'm guessing I should use the none then, but this also allows adding semver label too, so... WAT?! :D

Currently I have

    "skipReleaseLabels": [
      "documentation",
      "skip-release",
      "devDeps",
      "infra"
    ],
    "labels": {
      "deps": {
        "name": "deps",
        "title": "🔩 Dependency Updates"
      },
      "devDeps": {
        "name": "devDeps",
        "title": "🔩 Dependency Updates"
      },
      "documentation": {
        "name": "documentation",
        "title": "🗒️ Documentation"
      },
      "core": {
        "name": "core",
        "title": "📦 Core"
      }
    },

and I want to skip on docs, skip-release, devDeps and infra, but don't want to skip on deps for example. Because I'm using renovate and want patch releases on fix(deps).

I also have onlyPublishWithReleaseLabel enabled anyway so it won't be some huge problem for me.

And one more thing, is changelogTitle on the next dist-tag? I just asking for clarification, because it's not shown in the PR.

[hipstersmoothie]

@tunnckoCore I think you setup would look like this in the new way:

{
  "labels": [
    {
      "name": "deps",
      "title": "🔩 Dependency Updates",
      // when deps are merged create a patch release
      "releaseType": "patch"
    },
    {
      "name": "devDeps",
      "title": "🔩 Dependency Updates",
      "releaseType": "none"
    },
    {
      "name": "documentation",
      "title": "🗒️ Documentation",
      "releaseType": "none"
    },
    {
      "name": "core",
      "title": "📦 Core",
      "releaseType": "patch"
    }
  ]
}

The none effectively acts as a skip. But if you really needed to release a devDep update you could add patch and a release would be made. This differs from adding a skip label, which would skip the release regardless of other labels.

changelogTitle

I have not done this either. It is still just title. I will add this to my PR for the refactor (still not on next. I'll get it out after changelogTitle )

[tunnckoCore]

Right. Okay, great :)

Issue was released in v8.0.0-next.8

Is it now? I'm guessing that prereleases are published on next? 🤔 Anyway, i'm not in rush. Still fighting with Yarn v2+pnp and building/bundling.

edit: And does missing title/changelogTitle still implies that it won't make a section in the Release notes?

[zephraph]

@tunnckoCore there's defaults on the changelog titles based on what version you're releasing.

[tunnckoCore]

I'm asking about the other "custom labels" that we add from the config and that are not about the semver. If I have infra label without title it won't get added, right? And when I have title (like in devDeps) it will be added.

[adierkens]

🚀 Issue was released in v8.0.0 🚀

[jrnail23]

@adierkens, it looks like this issue was the major impetus behind the v8 major rev, so I'm asking this question here... Is there anything special I need to do to upgrade to v8 from v7.x?

[hipstersmoothie]

If you have any extra labels or skipReleaseLabels you will need to use the new format

https://intuit.github.io/auto/pages/autorc.html#label-customization

[tunnckoCore]

Wooohooo! 🎉 I'll try it in the weekend.

[bnigh]

First of all, Cool changes for v8!

---

Regarding

Changelog titles can be added to labels, but it's not exactly clear in what order they take precedent. If minor and documentation labels both exist, which changelog title takes precedent?

From local testing, it seems that the current behavior is:

• assign the a given PR to the first label with truthy changelogTitle in priority order of the releaseType (major, minor, patch, then all others)
• if the PR has multiple labels associated with the same releaseType priority above, then PR is included in the section of the label defined in the config first (default labels precede all others)

Below are a few examples:

---

(1): minor and none labels
config:

"labels": [
  { "name": "typescript", "changelogTitle": "Typescript Change", "releaseType": "none" },
  { "name": "minor", "changelogTitle": "Enhancement", "releaseType": "minor" }
]

labels on PR:

typescript
minor

changelog label section: minor

• because minor releaseType has higher precedence

---

(2): multiple patch labels
config:

"labels": [
  { "name": "typescript", "changelogTitle": "Typescript Change", "releaseType": "patch" },
  { "name": "core", "changelogTitle": "Core Change", "releaseType": "patch" }
]

labels on PR:

typescript
core

changelog label section: typescript

• because typescript label appears in config before core

---

(3): none label and default none label
config:

"labels": [
  { "name": "typescript", "changelogTitle": "Typescript Change", "releaseType": "none" }
]

labels on PR:

typescript
internal

changelog label section: internal

• because internal label appears in config before typescript (it appears in default config which takes highest precedence between the same releaseType

---

@hipstersmoothie, Is the above behavior / precedence order intended?

If so, it would be good to add to documentation so it is clear how the changelog label sections are generated and how sections take precedence (I could help out with this if needed)

If not, can we work to define a precedence order, either as part of this issue or another?

[tunnckoCore]

I don't see it as something special or wrong. It seems intuitive enough. The only important thing is major, minor and patch to be always first in the changelog, just because it's kind of standard thing. But even if order is configurable, it's okay too.