feat(types): add generic type parameters to changelog functions

[spencerbeggs]

Enhances type safety by allowing changelog generators to specify custom option types instead of using generic any types

fixes #1722

[changeset-bot]

🦋 Changeset detected

Latest commit: b020a8f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 15 packages

Name	Type
@changesets/types	Minor
@changesets/changelog-github	Patch
@changesets/apply-release-plan	Patch
@changesets/assemble-release-plan	Patch
@changesets/changelog-git	Patch
@changesets/cli	Patch
@changesets/config	Patch
@changesets/get-dependents-graph	Patch
@changesets/get-release-plan	Patch
@changesets/parse	Patch
@changesets/pre	Patch
@changesets/read	Patch
@changesets/release-utils	Patch
@changesets/should-skip-package	Patch
@changesets/write	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.69%. Comparing base (9657b26) to head (b020a8f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1723   +/-   ##
=======================================
  Coverage   80.69%   80.69%           
=======================================
  Files          54       54           
  Lines        2264     2264           
  Branches      684      685    +1     
=======================================
  Hits         1827     1827           
  Misses        432      432           
  Partials        5        5           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[spencerbeggs]

@Ari4ka I updated updated the branch so it it even with main. Thanks for reviewing.

[Andarist]

The description of this PR mentions:

Enhances type safety by allowing changelog generators to specify custom option types instead of using generic any types

But what is being introduced here, let's be real, is kind of a cast that disguises itself as being safe.

The type safe alternative would be to just type params as unknown and force the user to cast it or refine with schemas or manual runtime checks.

[spencerbeggs]

@Andarist If I understand you correctly, this solution is not true type safety because the shape of the argument is being parsed from JSON and we can't enforce that at runtime. My solution of converting the types to be generics with a default value like it was before was simply for the ergonomics of developers working on their own changelog systems. Would an acceptable compromise be for me to make a note of this issue in the JSDoc comments and demonstrate validating the shape of the argument in an @example remark? That way we can have our types and validate them, too? I can also add some documentation elsewhere if you would like. I appreciate you taking the time to review this. I am a big fan of this project.

[Andarist]

This kind of a thing is ultimately always a decision up to personal tastes. Many APIs out there compromise type-safety in favor of improved ergonomics. I can sympathize with that goal but I'm not sure if I end up on the same side of this argument.

The problem with this is that it's an illusion of type-safety - you, as author of this change, will understand the risks. I'll understand the risks, some of the skilled devs will understand the risks and people who read the docs might also understand the risks. But those combined groups do not constitute all developers of Changesets.

I recognize the current types there aren't really safe anyway but I just think it would be better to change those in the future to unknown for what can't be typed. Would the ergonomics of this really be that worse?

const myChangelog: ChangelogFunctions = {
  getReleaseLine: async (changeset, type, _options) => {
    const options = _options as { repo: string };
    return `- ${changeset.summary}`;
  },
};

I know it's slightly worse but at least the true behavior of this code isn't hidden/tucked away.

[spencerbeggs]

@Andarist I see what you are saying. I was just working on a Changelog generator in TypeScript and found this hard to grok and thought perhaps adding this sugar would help other developers. I would still advocate for adding this as it doesn't change the current API at all. All the hidden perils of not validating the options input still exist, both before and after, but at least there is clearer indication about what is happening. I am just trying to be helpful, but if this isn't something you are interested in adding, I totally understand.