KhronosGroup / KhronosGroup/Vulkan-Docs

[enhancement] Specify behavior in the form of Valid Behavior lists

Open
#2,004 2 comments 0 reactions 1 assignee View on GitHub

@Tobski is already working on this.

Since Dec 14, 2022.

Dominant language
JavaScript
Stars
3.3k
Forks
549
Avg merge
5d 5h
Merged PRs (30d)
2

Description

For the most part I like Valid Usage sentences (they could use some thematic organization though, and some other QoL tweaks; I have some ideas there too). The good part is they incentivize the text author to form the requirement in atomic, complete, formal, structured, and normatively forceful (i.e. "must" sentence) manner. While free text incentivizes more colloquial descriptions that also convolute multiple aspects together.

So I wonder if there should equally be Valid Behavior lists, which would analogically enumerate the requirements of the implementation. For commands that return some struct, it would be virtually same as VUs, describing the restrictions on the returned values. Additionally it should mention all the return codes (could be partly Implicit Valid Behavior where the meaning of return code is uniform across all commands, at the risk of being more spammy for the sake of completeness). For more complicated behavior it might help in describing the behavior in more thoughtful and modular manner, and make it easier to review for completeness and accuracy, and it might help being referencable (analogously via VBID), which might also be useful for CTS organization and coverage tracking.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.