[Docs] Source traceability and game title ban

This commit is contained in:
Triang3l 2021-09-05 21:34:38 +03:00
parent e720e0a540
commit ddb08c60c2
1 changed files with 54 additions and 0 deletions

View File

@ -34,6 +34,60 @@ up later, so be sure to check it out.
Basically: run `xb format` before you add a commit and you won't have a problem.
## Referencing Sources
In code interacting with guest interfaces or protocols, where applicable, please
leave comments describing how the information included in it was obtained. For
code based on analysis of the response of the original Xbox 360 hardware or
software, please provide reproduction information, such as an outline of the
algorithm executed, arguments and results of function calls or processor
instructions involved, GPU or XMA commands and state register changes. Having
traceable sources helps solve multiple issues:
* The legality of the submitted code can be verified easily.
* Additional analysis based on reproduction steps from prior research can be
done to discover more details or to research the behavior of other related
features.
* The accuracy and completeness of the information can be evaluated. Knowing
whether something is ground truth about the console's behavior or an
approximation (for example, based on similar functionality in Windows, the
Qualcomm Adreno 200 GPU, AMD's desktop GPU architectures; the Direct3D 11.3
functional specification, which may be used as a generic fallback when no
information specific to the Xenos or Direct3D 9 is available) may help avoid
redoing work that has already been done if the findings are accurate, or
making potentially wrong conclusions about related functionality if there's no
certainty about the correctness of the information. In addition, it's useful
to describe how complete the implementation of a feature is — such as edge
cases checked and covered. If you are unsure if your code accurately reflects
the behavior of the console, or you have deliberately made deviations due to
the lack of prerequisites for an accurate implementation or for performance
reasons (in case of the latter, it's recommended to provide both options,
selectable with a configuration variable), or you just want more research to
be done in the future, please leave a TODO comment in the format provided in
[style_guide.md](../docs/style_guide.md).
If you have verified your code by checking the correctness of the behavior of a
game, **do not** refer to it by its title trademark. To avoid unnecessary
dependencies on third parties, instead, use the hexadecimal title ID number
displayed in the title bar beside the name of the game.
Do not leave any hard-coded references to specific games, even in title ID form,
in any part of the user interface, including the configuration file. If you want
to provide an example of a game where changing a configuration variable may have
a noticeable effect, use a code comment near the declaration of the variable
rather than its description string. Any game identifiers referenced in the user
interface must be obtained only from information provided by the user such as
game data files.
Also, do not put any conditionals based on hard-coded identifiers of games — the
task of the project is researching the Xbox 360 console itself and documenting
its behavior by creating open implementations of its interfaces. Game-specific
hacks provide no help in achieving that, instead only complicating research by
introducing incorrect state and hiding the symptoms of actual issues. While
temporary workarounds, though discouraged, may be added in cases when progress
would be blocked otherwise in other areas, they must be expressed and reasoned
in terms of the common interface rather than logic internal to a specific game.
## Clean Git History
Tools such as `git bisect` are used on the repository regularly to check for and