nodejs / nodejs/node

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

Offen
#52,935 5 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

feature request never-stale node-api
Vorherrschende Sprache
JavaScript
Sterne
122k
Forks
37.3k
Ø Merge
4 T. 2 Std.
Gemergte PRs (30 T.)
283

Beschreibung

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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Es werden keine Implementierungsdateien oder Tests genannt. Beginne damit nachzuverfolgen, wie die Node-API-Version napi_env erreicht und wie experimentelle Funktionen zur Laufzeit dargestellt werden; als erledigt gilt die Aufgabe, wenn Opt-out-Entscheidungen in der gemeldeten Version codiert sind und die vorgeschlagenen Feature-Flag-Prüfungen bereitgestellt werden, ohne das Verhalten veröffentlichter Versionen zu ändern.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
node.js
Bereich
api
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
30/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.