Unstable APIs in stable packages should be more clearly marked as unstable

[kt3k]

Currently we add the note @experimental **UNSTABLE**: New API, yet to be vetted. to the docs of unstable APIs. However there are feedbacks that this note is not enough for making the users aware of the unstableness of those APIs, and there are too high chance that users unintentionally start using them.

We currently consider moving unstable APIs under unstable- prefixed export paths. For example, (unstable) route API in @std/http becomes:

-import { route } from "@std/http/route";
+import { route } from "@std/http/unstable-route";

---

• std/assert
  • assertNever function
• std/cli BREAKING(cli/unstable): move spinner module to unstable-spinner #5946
  • Spinner class
  • SpinnerOptions type
  • Color type (part of SpinnerOptions)
• std/data-structures
  • BidirectionalMap class
• std/encoding
  • Base32EncoderStream class
  • Base32DecoderStream class
  • Base32HexEncoderStream class
  • Base32HexDecoderStream class
  • Base64EncoderStream class
  • Base64DecoderStream class
  • Base64UrlEncoderStream class
  • Base64UrlDecoderStream class
  • HexEncoderStream class
  • HexDecoderStream class
  • encodeBase32Hex function
  • decodeBase32Hex function
• std/front-matter/yaml BREAKING(front-matter/unstable): move unstable overload of yaml extract to unstable-yaml #5968
  • extract function (the overload with option)
• std/html
  • isValidCustomElementName function
• std/http refactor(http): move unstable APIs (header, method, signed-cookie) #5938
  • HEADER value
  • Header type
  • METHOD value
  • Method type
  • Handler type
  • Route type
  • route function BREAKING(http/unstable): move route module to unstable-route #5939
  • signCookie function
  • verifySignedCookie function
  • parseSignedCookie function
• std/net
  • getNetowrkAddress function
• std/path
  • basename function (URL overload) BREAKING(path/unstable): move unstable overload of basename to unstable-basename #5957
  • dirname function (URL overload) BREAKING(path/unstable): move unstable overload of dirname to unstable-dirname #5954
  • extname function (URL overload) BREAKING(path/unstable): move unstable overload of extname to unstable-extname #5962
  • join function (URL overload) BREAKING(path/unstable): move unstable overload of join to unstable-join #5964
  • normalize function (URL overload) docs(path): add note about unstable-join #5967
• std/path/posix
  • basename function (URL overload) BREAKING(path/unstable): move unstable overload of basename to unstable-basename #5957
  • dirname function (URL overload) BREAKING(path/unstable): move unstable overload of dirname to unstable-dirname #5954
  • extname function (URL overload) BREAKING(path/unstable): move unstable overload of extname to unstable-extname #5962
  • join function (URL overload) BREAKING(path/unstable): move unstable overload of join to unstable-join #5964
  • normalize function (URL overload) docs(path): add note about unstable-join #5967
• std/path/windows
  • basename function (URL overload) BREAKING(path/unstable): move unstable overload of basename to unstable-basename #5957
  • dirname function (URL overload) BREAKING(path/unstable): move unstable overload of dirname to unstable-dirname #5954
  • extname function (URL overload) BREAKING(path/unstable): move unstable overload of extname to unstable-extname #5962
  • join function (URL overload) BREAKING(path/unstable): move unstable overload of join to unstable-join #5964
  • normalize function (URL overload) docs(path): add note about unstable-join #5967
• std/streams
  • toLines function
  • FixedChunkStream class
• std/text
  • toConstantCase function
  • slugify function
• std/uuid BREAKING(uuid/unstable): move v7 module to unstable-v7 #5937
  • v7 namespace
• std/uuid/v7 BREAKING(uuid/unstable): move v7 module to unstable-v7 #5937
  • generate function
  • validate function
  • extractTimestamp function

[BlackAsLight]

With the current note, are you trying to communicate that the public API is unstable in the sense that it might change drastically and in breaking ways or that it is free of malicious intent?

When I hear the word unstable, I get the impression that it might change in breaking ways, but the latter part of the note "yet to be vetted" sounds like that's not the message trying to be communicated here.

[timreichen]

How about logging a warning?

[kt3k]

@BlackAsLight

With the current note, are you trying to communicate that the public API is unstable in the sense that it might change drastically and in breaking ways or that it is free of malicious intent?

It means it can be changed in breaking ways in the future. The phrase is traditionally used in CLI's API docs. Maybe it can be worded in a better way

@timreichen

How about logging a warning?

That might be another option, but there's also an opinion from the core team that it should be visible in sample code. (Warnings are only visible at runtime)

[iuioiua]

How about logging a warning?

I'd rather not. We did this for deprecated APIs in preparation for Deno 2 and quickly reverted it, even with environment variables that disabled it. It seemed to cause more annoyance than provide help.

[kt3k]

These 51 APIs are targets of this change.

https://gist.github.com/kt3k/f6754c2fa5b90cc6ef7c03396aa90b37

[iuioiua]

@kt3k, if you have time, would you be able to create a checklist for the modules that need to migrate? I can probably work through this tomorrow.

[kt3k]

Added the task list in the first comment.

[kt3k]

All unstable items in stable packages have been migrated to unstable-<api> name paths.