docs(NODE-7396): document experimental features#4873
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for all experimental features in the MongoDB Node.js Driver v7.1.0. The documentation catalogues 31 experimental annotations across 9 major feature categories, providing developers with a single reference point for understanding which APIs may undergo breaking changes in future releases.
Changes:
- Added EXPERIMENTAL_FEATURES.md documenting all experimental features with descriptions, code examples, source file references, and stability notes
- Organized features into logical categories including resource management, timeouts, encryption, and strict TypeScript types
- Included practical usage examples and warnings about production readiness for each experimental feature
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
RaschidJFR
force-pushed
the
NODE-7396/experimental_feature_report
branch
from
041a977 to
e9ec56a
Compare
| ### Explicit Resource Management | ||
|
|
||
| **Status**: ⚠️ Experimental (until TC39 proposal completion) |
There was a problem hiding this comment.
The proposal is complete for Explicit Resource Management 🎉
There was a problem hiding this comment.
Copleted? I see the proposal is in Stage 3:
https://github.com/tc39/proposal-explicit-resource-management
There was a problem hiding this comment.
I'm not sure where on that page I see anything saying the current stage.
But it's listed here in finished proposals!
https://github.com/tc39/proposals/blob/main/finished-proposals.md
There was a problem hiding this comment.
The proposal is finished indeed. Should we say then "Experimental until native await using is available on all supported Node.js versions."
|
|
||
| ### Timeout Management | ||
|
|
||
| **Status**: ⚠️ Experimental |
There was a problem hiding this comment.
All statuses are experimental and things that are no longer experiment will be removed from this document right? so maybe this is redundant but I think a good replacement would be a **Path To Stable**: ... section
There was a problem hiding this comment.
That would be very useful. I don't know if we have an explicit path-to-stable for every feature tho.
| #### `StrictMatchKeysAndValues<TSchema>` | ||
| **Source**: [src/mongo_types.ts](https://github.com/mongodb/node-mongodb-native/blob/v7.2.0/src/mongo_types.ts) |
There was a problem hiding this comment.
Is this important to elevate to its own section? it's unlikely users would interact with this type directly
There was a problem hiding this comment.
They are still experimental and public. I think they should be documented under the Typescript Types section.
| | [Timeout Management](#timeout-management) | Control operation timeouts with `timeoutMS` | v6.6.0 | | ||
| | [Client-Side Encryption Key Management](#client-side-encryption-key-management) | Custom key material and rewrap APIs | v6.0.0 | | ||
| | [Strict TypeScript Types](#strict-typescript-types) | Enhanced type safety for filters and updates | v5.0.0 | | ||
| | [Encrypted Fields](#encrypted-fields) | Schema for encrypted collections | v4.6.0 | |
There was a problem hiding this comment.
Some of these features have been experimental for a while. It would be nice to explain what's happening with some of these "older" features: will we remove the experimental label? If so, when? And how do we pick which features will be experimental vs "core"?
There was a problem hiding this comment.
@RaschidJFR , can we expand a bit on the policies around the experimental label? Or link to our existing docs, if this is covered elsewhere?
tadjik1
requested review from
PavelSafronov and
nbbeeken
and removed request for
dariakp
Description
Closes NODE-7396
Summary of Changes
Adds EXPERIMENTAL_FEATURES.md documenting all 31 experimental annotations in the driver (v7.1.0). Includes descriptions, code examples, and source links for each experimental feature.
Notes for Reviewers
Need a hand reviewing the accuracy of the content added.
Release Highlight
Release notes highlight
Added EXPERIMENTAL_FEATURES.md providing comprehensive documentation of all experimental features in the driver, including usage examples and stability notes.
Double check the following
npm run check:lint)type(NODE-xxxx)[!]: descriptionfeat(NODE-1234)!: rewriting everything in coffeescriptChanges are covered by testsNew TODOs have a related JIRA ticket