From 955a0942f10c7c9e981cac3cb2ae2f5f4e227cf1 Mon Sep 17 00:00:00 2001 From: Rickey Date: Sun, 21 Dec 2025 17:27:03 -0800 Subject: [PATCH] Add contributing guide (#334) * Add contributing guide * small format changes for CONTRIBUTING.md * Update CONTRIBUTING.md Co-authored-by: MeirGavish * Update CONTRIBUTING.md with more clang-format * Move stuff around for CONTRIBUTING * Update VScode instructions * Remove recommendation for formatOnSave * Update the clang-format thing again * Update CONTRIBUTING.md Co-authored-by: MeirGavish --------- Co-authored-by: MeirGavish --- CONTRIBUTING.md | 89 ++++++++++++++++++++ Doxyfile | 2 +- README.md | 4 + scripts/{build_bug_report.py => get_hash.py} | 2 +- 4 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md rename scripts/{build_bug_report.py => get_hash.py} (92%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a3befed --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Developer Guide + +Thank you for reading this. Below is a quick summary of expectations and tips to contribute. + +## CI Checks +On pull-requests, various checks will be performed: +1. **Formatting**: `clang-format` will be ran on every `.c/.h` file with [this configuration](https://github.com/GBALATRO/balatro-gba/blob/main/.clang-format). Failures will cause the CI to fail. +2. **Unit Tests**: Unit tests are required to pass and are located in the repo [here](https://github.com/GBALATRO/balatro-gba/tree/main/tests). +3. **Rom Build**: The ROM must successfully build with the `make -j$(nproc)` command. + +## Code Style +Besides the automatic formatting checks from `clang-format`, there is a looser set of code style rules. These are not strictly required, but is encouraged to be followed. +The following details the code style rules including the enforced clang-format style. +[Link in wiki](https://github.com/GBALATRO/balatro-gba/wiki/Code-Style-Guide) + +## Building Documentation +Doxygen is used to build documentation that can be opened in browser. + +[Link in wiki](https://github.com/GBALATRO/balatro-gba/wiki/Documentation-for-Developers) + +## Tools + +### clang-format + +Running `clang-format` locally is recommended before submitting a PR as it will fail the **CI Checks** if not properly formatted. It is recommended either: +1. Run `clang-format` periodically and only commit formatted code. +2. Run `clang-format` as a separate commit on larger changes, and review each modified hunk. + +Either way, just ensure you manually review automatic changes. + +#### VSCode + +The recommended setup for VSCode is to install the [**clangd**](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) extension. It will provide helpful information in VSCode and can be used to format the code automatically according to the `.clang-format` file with **`Ctrl+Shift+I`** + +There is an option to enable `"editor.formatOnSave"` in the VSCode `settings.json` file. You can also do this by opening the settings menu (`File->Preferences->Settings`) and searching `format on save`. + +#### Manually + +If installed locally and you'd prefer to use it in your shell. You can do the following + +```sh +# List warnings +clang-format --dry-run -Werror include/*.h source/*.c +# Modify all files inplace +clang-format -i include/*.h source/*.c +# Or just one +clang-format -i include/blind.h +``` + +#### Disabling Formatting + +Sometimes `clang-format` rules need to be broken, like in the case of the [joker registry](https://github.com/GBALATRO/balatro-gba/blob/8fb0813cf5f7235b6450dc9a76252dda4d9b4a27/source/joker_effects.c#L333) and other tables or maps. If it makes sense, you can wrap code in `// clang-format off` and `// clang-format on`: + +- **Without clang-format**: +```c +// clang-format off +const table_of_tables = +{ + { TABLE_A, 1, tableAMap }, + { TABLE_B, 2, tableBMap }, + { TABLE_C, 3, tableCMap }, + { TABLE_D, 4, tableDMap }, + { TABLE_E, 5, tableEMap }, + { TABLE_F, 6, tableFMap }, + { TABLE_G, 7, tableGMap }, +} +// clang-format on +``` +- **With clang-format**: +```c +const table_of_tables = +{ + {TABLE_A, 1, tableAMap}, {TABLE_B, 2, tableBMap}, {TABLE_C, 3, tableCMap}, + {TABLE_D, 4, tableDMap}, {TABLE_E, 5, tableEMap}, {TABLE_F, 6, tableFMap}, + {TABLE_G, 7, tableGMap}, +} +``` + +### Custom Scripts +In the repo we use custom scripts located in the [`scripts`](https://github.com/GBALATRO/balatro-gba/tree/main/scripts) directory. + +🟡 **Note**: `python3` and `bash` are required for these scripts. + +- **get_hash.py**: Get git hash from ROM. +- **generate_font.py**: Generate a font manually. +- **get_memory_map.sh**: Print the memory map of the pre-allocated pools. + +## Debugging +It's recommended to use [mGBA](https://mgba.io/) for ROM testing and debugging. As it provides a [`gdbserver`](https://en.wikipedia.org/wiki/Gdbserver) via the `-g` flag `mgba -g build/balatro-gba.gba`. You can connect via `gdb` or here is a [great guide for vscode](https://felixjones.co.uk/mgba_gdb/vscode.html). diff --git a/Doxyfile b/Doxyfile index b482f0c..e90a801 100644 --- a/Doxyfile +++ b/Doxyfile @@ -3017,4 +3017,4 @@ MSCFILE_DIRS = EXCLUDE = build tests graphics audio doc scripts -USE_MDFILE_AS_MAINPAGE = README.md +USE_MDFILE_AS_MAINPAGE = CONTRIBUTING.md diff --git a/README.md b/README.md index 9cdb945..470d3d8 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,10 @@ This **tech-demo/proof of concept** is strictly limited in content to a minimal (Hold A: Swap Owned Jokers in the Shop) +# Contributing + +If you would like to contribute, please read CONTRIBUTING.md. + # **Build Instructions:** ## **-Docker-** diff --git a/scripts/build_bug_report.py b/scripts/get_hash.py similarity index 92% rename from scripts/build_bug_report.py rename to scripts/get_hash.py index 017127a..42c0b9c 100644 --- a/scripts/build_bug_report.py +++ b/scripts/get_hash.py @@ -16,7 +16,7 @@ def grep_binary_offsets(path, pattern): if __name__ == "__main__": if len(sys.argv) < 2: - print("Usage: python script.py ") + print("Usage: python get_hash.py ") sys.exit(1) file_path = sys.argv[1]