nodejs / nodejs/node

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

Abierto
#52,935 5 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

feature request never-stale node-api
Lenguaje dominante
JavaScript
Estrellas
122k
Forks
37.3k
Merge medio
4 d 2 h
PR fusionados (30 d)
283

Descripción

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.

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Línea de trabajo

No se nombran archivos de implementación ni pruebas. Empieza rastreando cómo la versión de Node-API llega a napi_env y cómo se representan las funciones experimentales en tiempo de ejecución; se considerará terminado cuando las decisiones de exclusión estén codificadas en la versión reportada y se proporcionen las comprobaciones de feature flags propuestas sin cambiar el comportamiento de las versiones publicadas.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
node.js
Área
api
Tipo de issue
Nueva funcionalidad
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
30/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.