OpenPunk/yuzu
1
0
Fork 0
mirror of https://github.com/yuzu-emu/yuzu.git synced 2024-11-27 00:30:06 +00:00
Code Issues Projects Releases Wiki Activity

Updated Contributing (markdown)

Narr the Reg 2024-01-10 11:45:33 -06:00
parent e516d50c8e
commit 0a16c3f777
1 changed files with 24 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
Contributing.md

@ -5,18 +5,34 @@
If you believe you have a valid issue report, please post text or a screenshot from the log (the console window that opens alongside yuzu) and build version (hex string visible in the titlebar and zip filename), as well as your hardware and software information if applicable. If you believe you have a valid issue report, please post text or a screenshot from the log (the console window that opens alongside yuzu) and build version (hex string visible in the titlebar and zip filename), as well as your hardware and software information if applicable.
# Contributing # Contributing
yuzu is a brand new project, so we have a great opportunity to keep things clean and well organized early on. As such, coding style is very important when making commits. We run clang-format on our CI to check the code. Please use it to format your code when contributing. However, it doesn't cover all the rules below. Some of them aren't very strict rules since we want to be flexible and we understand that under certain circumstances some of them can be counterproductive. Just try to follow as many of them as possible. yuzu is a brand new project, so we have a great opportunity to keep things clean and well organized early on. As such, coding style is very important when making commits. We run clang-format on our CI to check the code. Please use it to format your code when contributing. However, it doesn't cover all the rules below. Some of them aren't very strict rules since we want to be flexible and we understand that under certain circumstances some of them can be counterproductive. Just try to follow as many of them as possible.
# Using clang format (version 10.0) ## Using clang-format
When generating the native build script for your toolset, cmake will try to find the correct version of clang format (or will download it on windows). Before running cmake, please install clang format version 10.0 for your platform as follows:
A custom build target, that updates the formatting of *all* C++ source files when executed, is added only if clang format is found by cmake. Before running cmake, please install clang format.
### Install
Version should be 10 or above.
* Windows: do nothing; cmake will download a pre built binary for MSVC and MINGW. MSVC users can additionally install a clang format Visual Studio extension to add features like format on save. * Windows: do nothing; cmake will download a pre built binary for MSVC and MINGW. MSVC users can additionally install a clang format Visual Studio extension to add features like format on save.
* macOS: run `brew install clang-format`. * macOS: run `brew install clang-format`
* Linux: use your package manager to get an appropriate binary (e.g. on Fedora: `sudo dnf install clang-tools-extra`). * Linux: use your package manager to get an appropriate binary. e.g.:
* Fedora: `sudo dnf install clang-tools-extra`
* Ubuntu: `sudo apt install clang-format`
If clang format is found, then cmake will add a custom build target that can be run at any time to run clang format against *all* source files and update the formatting in them. This should be used before making a pull request so that the reviewers can spend more time reviewing the code instead of having to worry about minor style violations. On MSVC, you can run clang format by building the clang-format project in the solution. On macOS, you can either use the Makefile target `make clang-format` or by building the clang-format target in XCode. For Makefile builds, you can use the clang-format target with `make clang-format` ### Run
You should format before making a pull request so that the reviewers can spend more time reviewing the code logic instead of the style.
* Windows with MSVC: build the clang-format project in the solution
* macOS: either use `make clang-format` or build the 'clang-format' target in XCode
* Linux: run `ninja clang-format`
## Style guidelines
### General Rules ### General Rules
* A lot of code was taken from other projects (e.g. Citra, Dolphin, PPSSPP, Gekko). In general, when editing other people's code, follow the style of the module you're in (or better yet, fix the style if it drastically differs from our guide). * A lot of code was taken from other projects (e.g. Citra, Dolphin, PPSSPP, Gekko). In general, when editing other people's code, follow the style of the module you're in (or better yet, fix the style if it drastically differs from our guide).
* Line width is typically 100 characters. Please do not use 80-characters. * Line width is typically 100 characters. Please do not use 80-characters.
* Don't ever introduce new external dependencies into Core * Don't ever introduce new external dependencies into Core
@ -25,6 +41,7 @@ If clang format is found, then cmake will add a custom build target that can be
* Avoid the use of C-style casts and instead prefer C++-style `static_cast` and `reinterpret_cast`. Try to avoid using `dynamic_cast`. Never use `const_cast` except for when dealing with external const-incorrect APIs. * Avoid the use of C-style casts and instead prefer C++-style `static_cast` and `reinterpret_cast`. Try to avoid using `dynamic_cast`. Never use `const_cast` except for when dealing with external const-incorrect APIs.
### Naming Rules ### Naming Rules
* Functions: `PascalCase` * Functions: `PascalCase`
* Variables: `lower_case_underscored`. Prefix with `g_` if global. * Variables: `lower_case_underscored`. Prefix with `g_` if global.
* Classes: `PascalCase` * Classes: `PascalCase`
@ -32,9 +49,11 @@ If clang format is found, then cmake will add a custom build target that can be
* Namespaces: `PascalCase`, `_` may also be used for clarity (e.g. `ARM_InitCore`) * Namespaces: `PascalCase`, `_` may also be used for clarity (e.g. `ARM_InitCore`)
### Indentation/Whitespace Style ### Indentation/Whitespace Style
Follow the indentation/whitespace style shown below. Do not use tabs, use 4-spaces instead. Follow the indentation/whitespace style shown below. Do not use tabs, use 4-spaces instead.
### Comments ### Comments
* For regular comments, use C++ style (`//`) comments, even for multi-line ones. * For regular comments, use C++ style (`//`) comments, even for multi-line ones.
* For doc-comments (Doxygen comments), use `/// ` if it's a single line, else use the `/**` `*/` style featured in the example. Start the text on the second line, not the first containing `/**`. * For doc-comments (Doxygen comments), use `/// ` if it's a single line, else use the `/**` `*/` style featured in the example. Start the text on the second line, not the first containing `/**`.
* For items that are both defined and declared in two separate files, put the doc-comment only next to the associated declaration. (In a header file, usually.) Otherwise, put it next to the implementation. Never duplicate doc-comments in both places. * For items that are both defined and declared in two separate files, put the doc-comment only next to the associated declaration. (In a header file, usually.) Otherwise, put it next to the implementation. Never duplicate doc-comments in both places.