ci(changelog): add deprecation commits to changelog automation

[DitwanP]

Related Issue: #9975

Summary

Adds custom type list to lerna and release-please config files, and add a deprecation type to the list. This should allow for tracking deprecations in the change-logs

[jcfranco]

The issue seems primarily focused on documentation, so introducing a brand-new type for deprecations could be confusing (e.g., we sometimes deprecate purely with doc, and other times with a feature or fix).

The type object supports specifying a scope. Could we test if the following would address the request?

 {"type": "docs", "hidden": true},
 {"type": "docs", "scope": "deprecation", "hidden": false},

[benelan]

The issue seems primarily focused on documentation, so introducing a brand-new type for deprecations could be confusing (e.g., we sometimes deprecate purely with doc, and other times with a feature or fix).

The type object supports specifying a scope. Could we test if the following would address the request?

Yeah I like this idea, more specifically can you test if this works:

 { "type": "docs", "scope": "deprecation", "section": "Deprecations" },

[jcfranco]

Didn't realize I left out my suggestion 😅 (updated now), but let's proceed w/ @benelan's.

[DitwanP]

@jcfranco, @benelan

Yeah I like this idea, more specifically can you test if this works:
{ "type": "docs", "scope": "deprecation", "section": "Deprecations" },

So I want to make sure I understand what this suggestion and Franco's are asking for. Would this be a replacement for the deprecation type, so we would instead use the "docs" type with a scope of deprecation?

If so, it should be noted that it the change-log would only pickup deprecation commits with a format like this "docs(deprecation): This is a deprecation...." and would show up under the deprecations section like this:

Note that the scope would then always be "deprecation" instead of showing more specific scopes like the other change-log types (feat, fix).

[jcfranco]

Solid point. We would definitely lose some flexibility with the docs(deprecation) approach.

@DitwanP @benelan WDYT about tweaking the original solution to be more explicit, like deprecation-doc or similar, to indicate it's doc-only?

[DitwanP]

Solid point. We would definitely lose some flexibility with the docs(deprecation) approach.

@DitwanP @benelan WDYT about tweaking the original solution to be more explicit, like deprecation-doc or similar, to indicate it's doc-only?

@jcfranco
Do you mean have one type that's for deprecate and another for deprecate-doc?

You mentioned that sometimes we deprecate with purely docs and other times with a feat or fix, I thought that in those feat/fix cases is where the deprecate would come into play so that on the changelog there's an explicit section to list what was deprecated, but maybe that's not the case?

[jcfranco]

Do you mean have one type that's for deprecate and another for deprecate-doc?

I was suggesting the latter.

I thought that in those feat/fix cases is where the deprecate would come into play so that on the changelog there's an explicit section to list what was deprecated, but maybe that's not the case?

We can only use one type per commit, so I don't think we can easily split up deprecation code changes from a feat/fix.
For example, how would we use deprecate with this feat PR? Maybe I'm missing something? 🤔

[DitwanP]

For example, how would we use deprecate with this feat PR? Maybe I'm missing something? 🤔

So I thought something like that would now be

deprecate: remove widthScale....

or

deprecate(widthScale, heightScale): something something..."

[jcfranco]

That would work if the change is purely to deprecate a component member, but we often handle deprecations within a fix or feat. In the example above, the changelog would no longer display a feat entry.

[DitwanP]

That would work if the change is purely to deprecate a component member, but we often handle deprecations within a fix or feat. In the example above, the changelog would no longer display a feat entry.

@jcfranco

🤔 I get that we currently sometimes handle deprecations like that but I guess I'm confused because I thought we would now just do the deprecation separate from the feature or a fix PRs.

What do you have in mind for how having deprecate-docs would change things? Would it be used for the purely deprecation PRs and we would still sometimes bundle deprecations with feat/fix? Because in those cases we would just end up with the changelog listing deprecations under feat/fix sections instead of deprecations.

[jcfranco]

I thought we would now just do the deprecation separate from the feature or a fix PRs.

We can, but this adds, IMO, unnecessary overhead. In the example above, we need to add code to handle both the new prop and the deprecated one in the same PR. Not sure how we could separate those cleanly. Also, it'd be odd to not add a deprecation note when the new props are added.

[DitwanP]

@benelan the conversation between Franco and I continued on teams and we wanted your input on the pending solution. We currently are planning to use deprecate-docs in the manner described in this pending wiki update:

Do you have any objections to the empty commit option or perhaps a suggestion for another route we could take.

[benelan]

Yeah that works for me. We can add multiple changelog entries from a single PR in release-please:
https://github.com/googleapis/release-please#what-if-my-pr-contains-multiple-fixes-or-features

So we could create the PR title as the type doc/fix/feat, but include a deprecate tag as well.

[DitwanP]

@jcfranco I've made the changes based on Ben's suggestions.

Also updated the wording on the pending wiki update to reflect the proposed process, LMK what you think:

When a pull request is strictly intended to deprecate an existing feature or component, use the deprecate commit type. This type is reserved for noting changes under the "Deprecations" section of the changelog.

If deprecations are part of a broader change, such as introducing a new feature or making a fix, a deprecate entry can be added to the body of the PR following the format described in the release-please documentation.

[jcfranco]

That looks great! Thanks to both of youse!

The only note I have is to consider adding some example snippets to the wiki update.

[jcfranco]

📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝
📝⛔⛔⛔⛔📝⛔📝📝📝📝📝⛔📝⛔⛔⛔⛔📝📝⛔⛔⛔📝📝⛔⛔📝📝⛔📝📝📝⛔📝⛔⛔⛔⛔📝⛔📝
📝⛔📝📝⛔📝⛔📝📝📝📝📝⛔📝⛔📝📝📝📝⛔📝📝📝📝⛔📝📝⛔📝⛔⛔📝⛔⛔📝⛔📝📝📝📝⛔📝
📝⛔⛔⛔⛔📝⛔📝📝⛔📝📝⛔📝⛔⛔⛔📝📝📝⛔⛔📝📝⛔📝📝⛔📝⛔📝⛔📝⛔📝⛔⛔⛔📝📝⛔📝
📝⛔📝📝⛔📝⛔📝⛔📝⛔📝⛔📝⛔📝📝📝📝📝📝📝⛔📝⛔📝📝⛔📝⛔📝📝📝⛔📝⛔📝📝📝📝📝📝
📝⛔📝📝⛔📝📝⛔📝📝📝⛔📝📝⛔⛔⛔⛔📝⛔⛔⛔📝📝📝⛔⛔📝📝⛔📝📝📝⛔📝⛔⛔⛔⛔📝⛔📝
📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝📝