[Docs] Source traceability and game title ban
This commit is contained in:
parent
e720e0a540
commit
ddb08c60c2
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue