node-api: include experimental feature flags in add-on version reported at runtime
Nadie ha tomado este issue todavía.
- 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:
- A feature flag indicating that it is available within the
NAPI_EXPERIMENTALportion of the API. - An opt-out flag indicating that, although the add-on chose to use
NAPI_EXPERIMENTALit 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
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- 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