nodejs / nodejs/node

node-api: include experimental feature flags in add-on version reported at runtime

未关闭
#52,935 5 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

feature request never-stale node-api
主要语言
JavaScript
星标
122k
派生
37.4k
平均合并
4 天 3 小时
30 天内合并 PR
272

描述

This only applies to features that change the behaviour of existing APIs.

We currently have two flags for each experimental behaviour-changing API:

  1. A feature flag indicating that it is available within the NAPI_EXPERIMENTAL portion of the API.
  2. An opt-out flag indicating that, although the add-on chose to use NAPI_EXPERIMENTAL it does not wish to use this particular feature of the experimental bundle.

In order to avoid going down the experimental code path when running an add-on that chose to opt out of an experimental feature, we need to encode that choice in the version reported to the add-on loader.

If NAPI_EXPERIMENTAL is defined, all experimental features are turned on, unless, for any given feature, its opt-out flag is given.

We can include experimental flags in the version number reported at runtime as follows:

highest 16 bits lowest 16 bits
feature 1 feature 2 ... feature 16 NAPI_VERSION (latest released, i.e. 8, 9, 10, etc.)
or
NAPI_VERSION_EXPERIMENTAL (2147483647) All experimental features are requested

This value ends up on napi_env. At runtime we can check against the bits of this value to decide on the code path. We should probably create a family of macros for making decisions based on the feature flags.

At our Node-API meeting we concluded that we should introduce behaviour-changing features extremely sparingly, because, in order to ensure we do not break our users, even those that have opted into NAPI_EXPERIMENTAL, the testing complexity doubles with each feature we introduce.

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

没有指定实现文件或测试。首先追踪 Node-API 版本如何传达到 napi_env,以及实验性功能在运行时如何表示;完成的标准是在报告的版本中编码退出选择,并提供所提议的 feature-flag 检查,同时不改变已发布版本的行为。

由索引模型根据 Issue 内容生成。

评估

技术栈
node.js
领域
api
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
基本清楚
新手友好度
30/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。