[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.
|
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
|
## Clean Git History
|
||||||
|
|
||||||
Tools such as `git bisect` are used on the repository regularly to check for and
|
Tools such as `git bisect` are used on the repository regularly to check for and
|
||||||
|
|
Loading…
Reference in New Issue