nodejs / nodejs/node

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

Đang mở
#52,935 5 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

feature request never-stale node-api
Ngôn ngữ chính
JavaScript
Star
122k
Fork
37.4k
Merge trung bình
4 ngày 3 giờ
Pull request đã merge (30 ngày)
272

Mô tả

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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Không có tệp triển khai hoặc bài kiểm thử nào được nêu tên. Hãy bắt đầu bằng cách lần theo cách phiên bản Node-API đi tới napi_env và cách các tính năng thử nghiệm được biểu diễn khi chạy; công việc được xem là hoàn tất khi các lựa chọn opt-out được mã hóa trong phiên bản được báo cáo và cung cấp các kiểm tra feature flag được đề xuất mà không thay đổi hành vi của các phiên bản đã phát hành.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
node.js
Lĩnh vực
api
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
30/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.