Back to all reviewers

Version APIs with care

nodejs/node
Based on 7 comments
Other

When introducing new API features or changes, implement proper versioning to maintain stability and backward compatibility. Key practices: 1. Guard experimental features behind version flags

API Other

Reviewer Prompt

When introducing new API features or changes, implement proper versioning to maintain stability and backward compatibility. Key practices:

  1. Guard experimental features behind version flags
  2. Add new enum values only at the end of existing enums
  3. Maintain explicit version checks in implementation
  4. Document version dependencies clearly

Example:

// Good: New enum value added at end with experimental guard
typedef enum {
  napi_uint32_array,
  napi_float32_array,
  napi_float64_array,
#ifdef NAPI_EXPERIMENTAL
  napi_float16_array,  // New experimental feature
#endif
} napi_typedarray_type;

// Good: Implementation with version check
if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) {
  // Handle non-experimental version appropriately
}

This approach ensures API stability, enables proper testing between versions, and provides clear migration paths for API consumers.

7
Comments Analyzed
Other
Primary Language
API
Category

Source Discussions