Re: Decision Record?

For some aspects of the API - limits and a few bits of terminology - we've
been slowly maintaining this doc:
https://gpuweb.github.io/gpuweb/correspondence/
Ideally I'd like to have more details about different features too. The
question about generating mipmaps, for example, could definitely be
answered there - it's something in some other APIs that has no
correspondence in WebGPU.
The timestamp one is unfortunately still in the air with #3952
<https://github.com/gpuweb/gpuweb/issues/3952>, but that shouldn't prevent
us from documenting it, especially since it's a limitation compared to some
other APIs (at least on hardware where more flexible timestamps have valid
behavior).

That said, documenting all this history is a bunch of work, and the spec
editors have barely had time for fixing problems in the actual spec. I find
a lot of stuff by searching the GitHub tracker, but sometimes it doesn't
work because we've renamed things over and over again through the history
of the project. FWIW Google does a pretty good job indexing it - about 25%
of the time I try to Google a question about how something works in Vulkan,
D3D12, or Metal, our own corresponding gpuweb issue comes up :)

Contributions to documenting this history would be welcome, either in that
doc or on external sites. Either way it's useful to developers!

-Kai (he/they)


On Wed, Feb 14, 2024 at 8:12 PM Dominic Cerisano <dcerisano@gmail.com>
wrote:

> You seem to have already found the decision records -  the github gpuweb
> Closed Issue and Closed PR records.
> You are also correct that the working group meeting minutes provide more
> insight into decision making processes behind these decision records.
> There are also Matrix groups, WC3 meetings and Office Hours where
> questions can be asked (using comments on Google Meet).
>
> Being somewhat familiar with the process, be assured that there have been
> a tremendous amount of decisions and supporting detail recorded. I have
> suggested training an LLM with all this material to be able to answer
> adhoc questions and even generate code.
>
> *Dominic Cerisano*
>
> dcerisano@gmail.com
>
>
>
> NOTICE: Confidential message which may be privileged. Unauthorized
> use/disclosure prohibited.
> AVIS : Message confidentiel dont le contenu peut être privilégié.
> Utilisation/divulgation interdites sans permission.
>
>
> On Wed, Feb 14, 2024 at 3:02 AM Tarek Sherif <tareksherif@pm.me> wrote:
>
>> Hi all,
>>
>> First off, just want to say great work with the spec. I've been
>> experimenting with WebGPU more lately, and it's a HUGE ergonomics upgrade
>> from WebGL. I'm finding it a joy to use (and I don't think I've ever said
>> that about a graphics API).
>>
>> One thing I've found challenging as I'm on-boarding to WebGPU is
>> understanding why some functionality I'm used to in WebGL doesn't exist in
>> the new API. Recent examples:
>>
>>    - Why can't the API generate mipmaps for me? Found the answer here
>>    <https://github.com/gpuweb/gpuweb/issues/386>.
>>    - My can't I time a set of arbitrary commands on the GPU? Found
>>    answers here <https://github.com/gpuweb/gpuweb/issues/2046> and here
>>    <https://github.com/gpuweb/gpuweb/wiki/GPU-Web-2023-11-08#problem-measuring-time-deltas-with-writetimestamp-3952>
>>    .
>>
>>
>> As you can see, the answers I wanted are available, but can be obscure
>> and require parsing long conversations. I'm wondering if the working group
>> would consider maintaining a sort of decision record or FAQ of more
>> substantial or controversial departures from WebGL and the reasoning behind
>> them, maybe even just with links out to relevant meeting minutes or GitHub
>> issues. I've found the WebGPU from WebGL
>> <https://webgpufundamentals.org/webgpu/lessons/webgpu-from-webgl.html>
>> article on WebGPU Fundamentals extremely helpful as a starting point, but
>> it doesn't provide reasons for the differences, which I think are valuable
>> to anyone who wants to be a serious practitioner. I also feel a document
>> like that could be of immense value to the real-time graphics community as
>> a whole, since your research seems to be uncovering a lot of interesting
>> details about the intersection of the current set of native graphics APIs.
>>
>> Best,
>>
>> Tarek Sherif
>> http://tareksherif.net/
>>
>>