chore: clarify the policy about new features

[kt3k]

No description provided.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.48%. Comparing base (9253dcb) to head (dc705c1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5581   +/-   ##
=======================================
  Coverage   96.48%   96.48%           
=======================================
  Files         465      465           
  Lines       37759    37759           
  Branches     5579     5579           
=======================================
  Hits        36432    36432           
  Misses       1285     1285           
  Partials       42       42           

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

[iuioiua]

I think it's good that this doesn't include timelines. LGTM.

[iuioiua]

I think we can make exceptions for APIs that we are highly confident will not yield unexpected behavior. E.g. #5573 is fine to add as stable.

[ry]

Do we have a mechanism to mark APIs as unstable? Is there a special jsdoc markup?

[kt3k]

Do we have a mechanism to mark APIs as unstable? Is there a special jsdoc markup?

Yes for symbols https://jsr.io/@std/cli/doc/~/Spinner (@experimental jsdoc tag seems translated to unstable label in the doc website.)

But I'm not sure about the way to mark specific parameter in function as unstable. (which is necessary for the case like #5573 )

cc @crowlKats

[kt3k]

I think we can make exceptions for APIs that we are highly confident will not yield unexpected behavior. E.g. #5573 is fine to add as stable.

Who are 'we' here? 1 maintainer, 2 maintainers, the core team, or the community? How to check we are highly confident?

[crowlKats]

@kt3k sadly both jsdoc and tsdoc dont have a way to mark unstable/experimental parameters. the only way i can think of is having overloads, where the overload with an unstable parameter is marked as unstable

[kt3k]

@crowlKats Ah, ok. Thanks for the input! Then we probably need to do overloads when an API is partially unstable.