Appropriate way to contribute a web API interface that is changing (Gamepad hapticActuators -> vibrationActuator)

[brettchalupa]

Summary

The Gamepad specification is in draft for for how force feedback (a.k.a. rumble, a.k.a. vibration) works. The specification within web-sys for hapticActuators is in Editor's Draft as of 09 August 2024 to change to:

[Exposed=Window]
interface Gamepad {
  readonly attribute DOMString id;
  readonly attribute long index;
  readonly attribute boolean connected;
  readonly attribute DOMHighResTimeStamp timestamp;
  readonly attribute GamepadMappingType mapping;
  readonly attribute FrozenArray<double> axes;
  readonly attribute FrozenArray<GamepadButton> buttons;
  [SameObject] readonly attribute GamepadHapticActuator vibrationActuator;
};

Notice the last line:

[SameObject] readonly attribute GamepadHapticActuator vibrationActuator;

hapticActuators has changed to vibrationActuator, and then the API for what that attribute is, a GamepadHapticActuator, has a new API:

[Exposed=Window]
interface GamepadHapticActuator {
  [SameObject] readonly attribute FrozenArray<GamepadHapticEffectType> effects;
  Promise<GamepadHapticsResult> playEffect(
      GamepadHapticEffectType type,
      optional GamepadEffectParameters params = {}
  );
  Promise<GamepadHapticsResult> reset();
};

This definition differs from what's currently enabled in GamepadHapticActuator.webidl

So my question is this: how does one go about contributing a change to an existing specification in this scenario? Would we add the new ones side-by-side with the existing? Or something else?

Additional Details

• the Gamepad hapticActuators API is only supported in Firefox (MDN) and is marked as experimental; it does not work from my testing
• the Gamepad vibrationActuator api is supported in Chrome, Edge, Opera, and Safari (MDN) and functions from my testing
• hapticActuators appears to be part of an older specification extension
• I couldn't find the WebIDL file that specifies the whole specification for Gamepad, but I think we can piece it together from https://w3c.github.io/gamepad/

Because many browsers do support the vibrationActuator property and it's in the Gamepad spec draft, it seems like it's the future standard; it'd be awesome is web-sys supported it for implementing rumble for controllers in WASM; that's the core motivation for this addition/change.

I'm happy to do the work to contribute this, but I figure since it's something changing, I should open an issue to start the conversation and get guidance. Thank you!

[daxpedda]

This API should probably not have been made stable in the first place, but fortunately none of these new additions require a breaking change to the already existing API.

Generally speaking we follow the spec no matter the browser support, but non-stable specifications should never override stable ones.

In this case adding all this new API unstably shouldn't be an issue and we can go ahead and deprecate the old API.

Let me know if you have any issues accomplishing any of this.

[brettchalupa]

@daxpedda thanks for the guidance, makes sense! I'll dig into adding the new API. Is there any reference/guidance for how to deprecate the old API?

[daxpedda]

To deprecate an API you just slap the [RustDeprecated] attribute on it.