diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e20dd4414..1404a5244 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -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