From 14775b424c405aad91556318f5c88ff688826c84 Mon Sep 17 00:00:00 2001 From: Josh Sanchez Date: Sun, 18 May 2025 21:27:30 -0500 Subject: [PATCH 1/6] Meta: First draft of contribution guidelines --- CONTRIBUTING.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..58bbe30f5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,29 @@ +The [Battle for Bikini Bottom Decompilation Project](https://github.com/bfbbdecomp/bfbb) is happy to accept all contributions of all size and scope! + +This documentation outlines our project contribution guidelines. Following these guidelines allows the maintainers review changes faster and give better feedback, and helps to ensure that future modding and PC port efforts are made as simple as possible. + +In addition to decompilation efforts, this project also welcomes tooling and [tutorial/knowledge resource](https://github.com/bfbbdecomp/bfbb-decomp-guide) contributions! Check out [our organization page](https://github.com/bfbbdecomp) to see all of the projects we ewlcome contributions to. + +## Contribution Guidelines + +Please respect the following guidelines: +- Ensure your code is formatted using the project's clang-format autoconfiguration ([VS Code Plugin](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format)). +- Keep pull requests scoped to a single compilation unit when possible. Defining functions in other files is encouraged, however, in cases where the function is used by the compilation unit you're contributing to. +- A good-faith attempt to clean up code generated by decompiler tools (m2c, Ghidra) is expected, using DWARF data and project code conventions as appropriate. +- Encourage and support other contributors, especially new ones! Decompiling games is hard and difficult work, but sharing knowledge and supporting fellow decompers makes that work a lot easier and more enjoyable for all of us. + +## Code Conventions +- Avoid using pointer math for unknown struct members. Instead, populate the struct with padding and the appropriate type using `unk_` as the naming convention. For example, define an unknown float member at offset 0xF0 as `F32 unk_F0`. +- Use the `TRUE`/`FALSE` macros in contexts where conditions use the value of a non-bool data type (S32, U8) as a boolean-like. +- Use the `NULL` macro when assigning `0`/`0x0` to a pointer value. +- Do not explicitly define enum values, unless the starting value is non-zero or the increment is non-standard. +- Use PowerPC naming conventions to provide variable names for values which have no symbols contained in the available DWARF data, i.e: +```cpp +U32 myFunc(U32 r3, U32 r4, F32 f1) +{ + U32 r17; + F32 f30; + + return r3; +} +``` From c60f53ad235a9e95cb23ad74e8dcecfab68bfb0d Mon Sep 17 00:00:00 2001 From: Josh Sanchez Date: Sun, 18 May 2025 21:37:28 -0500 Subject: [PATCH 2/6] Contrib: Fix typo in introduction --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58bbe30f5..788ef90a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ The [Battle for Bikini Bottom Decompilation Project](https://github.com/bfbbdeco This documentation outlines our project contribution guidelines. Following these guidelines allows the maintainers review changes faster and give better feedback, and helps to ensure that future modding and PC port efforts are made as simple as possible. -In addition to decompilation efforts, this project also welcomes tooling and [tutorial/knowledge resource](https://github.com/bfbbdecomp/bfbb-decomp-guide) contributions! Check out [our organization page](https://github.com/bfbbdecomp) to see all of the projects we ewlcome contributions to. +In addition to decompilation efforts, this project also welcomes tooling and [tutorial/knowledge resource](https://github.com/bfbbdecomp/bfbb-decomp-guide) contributions! Check out [our organization page](https://github.com/bfbbdecomp) to see all of the projects we welcome contributions to. ## Contribution Guidelines From 63374a2a55f4eef63dbfe8f8f2f6cbdfda2b210b Mon Sep 17 00:00:00 2001 From: Josh Sanchez Date: Wed, 21 May 2025 23:14:57 -0500 Subject: [PATCH 3/6] Doc: Clarify PowerPC naming convention expectations --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 788ef90a5..38606880e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,11 +17,12 @@ Please respect the following guidelines: - Use the `TRUE`/`FALSE` macros in contexts where conditions use the value of a non-bool data type (S32, U8) as a boolean-like. - Use the `NULL` macro when assigning `0`/`0x0` to a pointer value. - Do not explicitly define enum values, unless the starting value is non-zero or the increment is non-standard. -- Use PowerPC naming conventions to provide variable names for values which have no symbols contained in the available DWARF data, i.e: +- Use PowerPC naming conventions when creating placeholder variable names. Placeholders should only be used when no DWARF symbol data is available and the variable does not have a name that can be reasonably assigned based on its usage. ```cpp U32 myFunc(U32 r3, U32 r4, F32 f1) { U32 r17; + xLightKit* r17_2; F32 f30; return r3; From 6d96dd954acb940eed09638d5ec8cb99f6e4f014 Mon Sep 17 00:00:00 2001 From: Josh Sanchez Date: Wed, 21 May 2025 23:21:47 -0500 Subject: [PATCH 4/6] Doc: Conventions for hex-to-char literals and symbol name cases --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38606880e..e21691ff7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,8 @@ Please respect the following guidelines: - Use the `TRUE`/`FALSE` macros in contexts where conditions use the value of a non-bool data type (S32, U8) as a boolean-like. - Use the `NULL` macro when assigning `0`/`0x0` to a pointer value. - Do not explicitly define enum values, unless the starting value is non-zero or the increment is non-standard. +- Hexadecimal literals used as arguments for asset functions should be represented using char literals when it would improve the readability of the code (i.e 0x504c4154 -> 'PLAT'). +- When DWARF symbols are unavailable, ensure variables are named using camelCase and structs/classes are named using TitleCase, or snake_case if they exist only in an anonymous namespace. - Use PowerPC naming conventions when creating placeholder variable names. Placeholders should only be used when no DWARF symbol data is available and the variable does not have a name that can be reasonably assigned based on its usage. ```cpp U32 myFunc(U32 r3, U32 r4, F32 f1) From 5e3879cd413645de1604308fc1d83e14ffe72b60 Mon Sep 17 00:00:00 2001 From: Josh Sanchez Date: Thu, 22 May 2025 00:14:58 -0500 Subject: [PATCH 5/6] Doc: Clarify PR scope contribution guideline --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e21691ff7..03a090484 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ In addition to decompilation efforts, this project also welcomes tooling and [tu Please respect the following guidelines: - Ensure your code is formatted using the project's clang-format autoconfiguration ([VS Code Plugin](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format)). -- Keep pull requests scoped to a single compilation unit when possible. Defining functions in other files is encouraged, however, in cases where the function is used by the compilation unit you're contributing to. +- Keep pull requests scoped to a single compilation unit when possible. However, defining functions in other files is encouraged in cases where the function is used by the compilation unit you're contributing to. - A good-faith attempt to clean up code generated by decompiler tools (m2c, Ghidra) is expected, using DWARF data and project code conventions as appropriate. - Encourage and support other contributors, especially new ones! Decompiling games is hard and difficult work, but sharing knowledge and supporting fellow decompers makes that work a lot easier and more enjoyable for all of us. From 04be8806fc41d953eecbae9b9c3c4f83f9811fa0 Mon Sep 17 00:00:00 2001 From: Josh Sanchez Date: Thu, 22 May 2025 14:56:41 -0500 Subject: [PATCH 6/6] Docs: Add contrib guideline for functions that add cleanup work --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03a090484..a067b214c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,7 @@ Please respect the following guidelines: - Ensure your code is formatted using the project's clang-format autoconfiguration ([VS Code Plugin](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format)). - Keep pull requests scoped to a single compilation unit when possible. However, defining functions in other files is encouraged in cases where the function is used by the compilation unit you're contributing to. - A good-faith attempt to clean up code generated by decompiler tools (m2c, Ghidra) is expected, using DWARF data and project code conventions as appropriate. +- Avoid adding functions or data definitions that will need to be cleaned up and removed later for the sake of increasing matchingness in the short-term. - Encourage and support other contributors, especially new ones! Decompiling games is hard and difficult work, but sharing knowledge and supporting fellow decompers makes that work a lot easier and more enjoyable for all of us. ## Code Conventions