search

microsoft / TypeScript-DOM-lib-generator

Tool for generating dom related TypeScript and JavaScript library files
Apache License 2.0
620 stars 421 forks source link

Ambiguity in the Contribution Guidelines #1346

Open MasterKale opened 2 years ago

MasterKale commented 2 years ago

I'm interested in updating some WebAuthn-related types like AuthenticatorTransport and AuthenticatorAttestationResponse that have gained new properties and values in the wild, but these new values aren't represented in the respective types in TypeScript's DOM library.

After reading this repo's Contribution Guidelines, particularly the "When the type exists but is wrong" section, I think I should actually focus my efforts on proposing updates to MDN itself. Once MDN gets updated then eventually this project will pull them in, and the changes will then eventually make it into a subsequent version of TypeScript after deploying the changes here to the TypeScript repo. Is this understanding correct?

If so, could that part of the README get updated with a more explicit outline of this intended process for updating DOM lib definitions? The way things are now it lead me to performing a naive search of, for example, AuthenticatorTransport and ended up in inputfiles/overridingTypes.jsonc. However very little in here makes sense to me and I was left with the impression that that would be the way for me to accomplish my goal. I'm not kinda stuck wondering where to go next.

I'd love to contribute, but even after trying to learn the process it's still quite nebulous to me as a newcomer.

mathe42 commented 2 years ago

As I understand most API are pulled (over different sources) from the idl-definitions directly from the spec.

So most cases you have to change here. An example:

https://www.w3.org/TR/web-animations-1/#the-animatable-interface-mixin

The interface mixin Animatable has a function animate where the first param is of type object wich in typescript would be any so this is overwritten to a better type here

https://github.com/microsoft/TypeScript-DOM-lib-generator/blob/main/inputfiles/overridingTypes.jsonc#L10-L21

As the browsers use the IDL while implementing features those definitions are near 100% correct.

I would guess most of the type overrides are cases where we can make the IDL more specific.

This is also true for when you make functions generic.

saschanaz commented 2 years ago

Once MDN gets updated then eventually this project will pull them in, and the changes will then eventually make it into a subsequent version of TypeScript after deploying the changes here to the TypeScript repo. Is this understanding correct?

Yes, exactly. Data from MDN will reflect here e.g. #1365 adding new AuthenticatorAttestationResponse members.

I guess you are confused because AuthenticatorTransport is not covered in MDN. I guess the readme should mention which things are in MDN and which things are not, and perhaps more details about how overridingTypes works. (It basically works based on https://github.com/microsoft/TypeScript-DOM-lib-generator/blob/main/src/build/types.d.ts)