From 396814ee09d8897cfa4e1eb24e01e7603c0309a1 Mon Sep 17 00:00:00 2001 From: Mallow Date: Fri, 9 Oct 2026 18:33:34 +0900 Subject: [PATCH 1/5] refactor: update CONTRIBUTING.md to streamline coding standards section and remove outdated guidelines --- CONTRIBUTING.md | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 560d113..c52233c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,9 +28,6 @@ ┕ [Pull Request Process](#pull-request-process) ┕ [Code Review](#code-review) [Coding Standards](#coding-standards) -┕ [Style Guide](#style-guide) -┕ [Naming Conventions](#naming-conventions) -┕ [Performance & Memory Guidelines](#performance--memory-guidelines) [Testing](#testing) ┕ [Writing Unit Tests](#writing-unit-tests) ┕ [Running the Test Suite](#running-the-test-suite) @@ -598,19 +595,14 @@ _wip..._ ## Coding Standards -_wip..._ - -### Style Guide - -_wip..._ - -### Naming Conventions - -_wip..._ - -### Performance & Memory Guidelines +For a project of this scale, maintaining a consistent coding style is crucial for readability, +maintainability, and collaboration. We have established a set of coding standards that all +contributors are expected to follow. -_wip..._ +For a detailed breakdown of our coding standards, please refer to the +[Coding Standards](./docs/Programming%20With%20C++/Coding%20Standard.md) document. It covers topics +such as naming conventions, formatting rules, and best practices for writing clean and efficient +C++ code. ## Testing @@ -636,6 +628,10 @@ _wip..._ _wip..._ +### Architectural Design Records (ADRs) + +_wip..._ + ## Community & Getting Help Getting stuck is a normal part of working on a complex C++ engine! Whether you need help configuring From 94bff18dc0e846d067a6f747b12231442ff0b48d Mon Sep 17 00:00:00 2001 From: Mallow Date: Fri, 9 Oct 2026 18:57:34 +0900 Subject: [PATCH 2/5] add: enhance bug reporting guidelines in CONTRIBUTING.md for clarity and detail --- CONTRIBUTING.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c52233c..1a37621 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -450,7 +450,30 @@ _wip..._ ### Reporting Bugs -_wip..._ +Found a bug or experiencing unexpected engine behavior? Clear, detailed bug reports help keep +`gp-engine` stable and reliable. Depending on the nature and severity of the issue, please use the +appropriate channel below: + +- **GitHub Issues (Preferred for Confirmed Bugs)**: If you have identified a clear bug, engine + crash, or build failure: + - Search existing [GitHub Issues][issues] to + ensure the bug has not already been reported. + - Open a new issue using the Bug Report template. + - Provide full context: operating system, LLVM/Clang version, CMake preset used, step-by-step + reproduction instructions, stack traces, and relevant log output. +- **GitHub Discussions & Discord (Preliminary Triage & Ambiguous Issues)**: If you are unsure + whether what you are seeing is a bug, a environment configuration issue, or expected engine + design: + - Start a topic on [GitHub Discussions][discussions] + under the Q&A or Support section. + - Join our [Discord Server][discord] to ask the community and maintainers in real time. + +> [!IMPORTANT] +> **Critical Security Vulnerabilities** +> Please **do not** report critical security flaws or sensitive vulnerabilities via public GitHub +> issues, discussions, or Discord channels. Instead, email us directly at +> . For additional guidelines, please refer to our +> [Security Policy](./SECURITY.md). ### Suggesting Enhancements @@ -640,9 +663,8 @@ you built with `gp-engine`, we are here to support you. **Where to Connect:** -- **Discord**: [Join our Discord Server](https://discord.graphical-playground.com) for real-time chat - with the maintainers and other developers. This is the best place for quick questions and informal - technical discussions. +- **Discord**: [Join our Discord Server][discord] for real-time chat with the maintainers and other + developers. This is the best place for quick questions and informal technical discussions. - **GitHub Discussions**: For longer-form questions, architectural proposals, or sharing your showcases, head over to [GitHub Discussions](https://github.com/orgs/GraphicalPlayground/discussions). - **Social Media**: Follow our updates and community highlights on [LinkedIn](https://www.linkedin.com/company/graphical-playground). @@ -685,3 +707,6 @@ _Thank you for being a part of the Graphical Playground. We can't wait to see wh ![Graphical Playground](https://github.com/GraphicalPlayground/.github/blob/main/assets/misc/gplayd-footer.svg) [gpbt]: https://github.com/GraphicalPlayground/gp-build-tool +[discord]: https://discord.graphical-playground.com +[discussions]: https://github.com/GraphicalPlayground/gp-engine/discussions +[issues]: https://github.com/GraphicalPlayground/gp-engine/issues From 1440b17cf88b755521561593a5861de44f183267 Mon Sep 17 00:00:00 2001 From: Mallow Date: Fri, 9 Oct 2026 19:16:18 +0900 Subject: [PATCH 3/5] add: enhance testing guidelines in CONTRIBUTING.md with detailed test philosophy and examples --- CONTRIBUTING.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 110 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a37621..0aaaf8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,5 @@ + ![Graphical Playground - Contribution Guidelines](https://github.com/GraphicalPlayground/.github/blob/main/assets/banners/gplayd-contributing.svg) 🌎 Read this in: [English](CONTRIBUTING.md) | [Español](translations/es/CONTRIBUTING.md) | [Français](translations/fr/CONTRIBUTING.md) | [简体中文](translations/zh-cn/CONTRIBUTING.md) @@ -29,12 +30,15 @@ ┕ [Code Review](#code-review) [Coding Standards](#coding-standards) [Testing](#testing) +┕ [Test Philosophy: Specialized & Isolated Testing](#test-philosophy-specialized--isolated-testing) +┕ [Activating Tests in a Module](#activating-tests-in-a-module) ┕ [Writing Unit Tests](#writing-unit-tests) ┕ [Running the Test Suite](#running-the-test-suite) [Documentation](#documentation) ┕ [Inline Code Documentation](#inline-code-documentation) ┕ [Writing Tutorials & Examples](#writing-tutorials--examples) [Community & Getting Help](#community--getting-help) + ## Code of Conduct @@ -629,15 +633,118 @@ C++ code. ## Testing -_wip..._ +Testing is a core requirement for maintaining the stability, performance, and correctness of +`gp-engine`. We enforce a rigorous testing discipline where core engine systems, mathematical +utilities, and platform wrappers must be accompanied by appropriate automated test coverage. + +Our build system, the [Graphical Playground Build Tool][gpbt] (GPBT), integrates test target +generation into our CMake toolchain. By default, [GoogleTest](https://github.com/google/googletest) +(GTest) is used across the codebase, but [Catch2](https://github.com/catchorg/Catch2) is also fully +supported for modules that prefer expressive BDD-style syntax. + +### Test Philosophy: Specialized & Isolated Testing + +To maintain speed, determinism, and maintainability, tests in `gp-engine` are categorized by scope +and responsibility: + +- **Unit Tests vs. Functional Tests**: + - **Unit Tests**: Focus strictly on isolated, low-level logic—such as math functions, memory + allocators, custom containers, and string parsing. Unit tests must not initialize heavy + subsystems (e.g., Vulkan device context, window creation, or audio servers) and must run in + milliseconds. + - **Functional & Integration Tests**: Validate high-level interactions between multiple engine + subsystems (e.g., scene graph updates propagating to render queues, or job system task + dependencies). +- **Hermetic & Deterministic**: Every test must be stateless, self-contained, and repeatable. + Tests should never depend on execution order, local filesystem state (unless using temporary + isolated directories), or GPU driver non-determinism without explicit tolerances. + +### Activating Tests in a Module + +Tests are organized per module within the `/source/` directory layout. You can activate test +generation for any engine module by invoking `gpEnableTests` inside the module's +`CMakeLists.txt` definition: + +```cmake +include(gp-build-tool) + +gpStartModule(core) + gpEnableTests() + + ... +gpEndModule() +``` + +> Note: If `FRAMEWORK` is not explicitly declared, GPBT automatically defaults to GoogleTest. ### Writing Unit Tests -_wip..._ +All test sources should reside inside a `tests/` directory within the respective module folder. + +#### 1. File & Test Naming Standards + +- File names must follow `.tests.cpp` (e.g., `Array.tests.cpp`). +- Test suite names should take the form `Test`. +- Individual test cases must use descriptive names that specify expected behavior: + `MethodName_Condition_ExpectedResult`. + +#### 2. GoogleTest Example + +```cpp +#include +#include "maths/vector/Vector3.hpp" + +namespace gp::math::tests +{ + +using FloatingPointTypes = ::testing::Types; +TYPED_TEST_SUITE(Vector3Test, FloatingPointTypes); + +TYPED_TEST(Vector3Test, DefaultConstructor) +{ + Vector3 vec; + + EXPECT_EQ(vec.x, this->zero); + EXPECT_EQ(vec.y, this->zero); + EXPECT_EQ(vec.z, this->zero); +} + +} // namespace gp::math::tests +``` + +#### 3. Catch2 Example + +```cpp +#include +#include +#include "maths/vector/Vector3.hpp" + +namespace gp::math::tests +{ + +SCENARIO("Vector3 default constructor initializes to zero", "[Vector3]") +{ + GIVEN("A Vector3 instance") + { + Vector3 vec; + + THEN("All components should be zero") + { + REQUIRE(vec.x == 0.0f); + REQUIRE(vec.y == 0.0f); + REQUIRE(vec.z == 0.0f); + } + } +} + +} // namespace gp::math::tests +``` ### Running the Test Suite -_wip..._ +Tests can be run across all platforms via CMake presets or CTest. Ensure you have configured the +engine using your target preset before attempting to execute tests. +You can also run tests directly from the command line or through your IDE's test runner. ## Documentation From 7fcffe45e3007f23a9be4e9a726c8f8c3b16cdf9 Mon Sep 17 00:00:00 2001 From: Mallow Date: Fri, 9 Oct 2026 19:19:40 +0900 Subject: [PATCH 4/5] add: enhance code review guidelines in CONTRIBUTING.md to clarify review process and merge requirements --- CONTRIBUTING.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0aaaf8d..f582c42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -618,7 +618,27 @@ _wip..._ ### Code Review -_wip..._ +Code review is a critical step in maintaining code quality, engine architecture integrity, and +performance across `gp-engine`. To ensure all contributions meet our standards, code reviews +follow strict review ownership and merge rules: + +- **Review Eligibility & Ownership**: Code reviews must be performed by project maintainers or + dedicated subsystem teams. +- **Automated Assignment via CODEOWNERS**: Reviewers are automatically assigned to pull requests + based on the modified files and subsystems, as defined in our [`CODEOWNERS`](./.github/CODEOWNERS) + file (e.g., changes to `/source/runtime/renderer/` will automatically notify and request review + from the Rendering team). +- **Merge Authority**: Only repository maintainers and administrators have permission to merge code + into protected integration and release branches (`main`, `dev`, `release-*`). + +> [!IMPORTANT] +> **Merge Requirements** +> Before a pull request can be merged into `main` or `dev`, it must satisfy all of the following +> conditions: +> +> 1. Formally approved by all designated code owners assigned via the `CODEOWNERS` file. +> 2. Pass all automated CI/CD checks (formatting, compilation across supported platforms, and unit tests). +> 3. Resolve all open review discussions and inline thread feedback. ## Coding Standards From de75bc90717f3f1cabbc59d94fcc2d5ffbda9848 Mon Sep 17 00:00:00 2001 From: Mallow Date: Fri, 9 Oct 2026 19:30:11 +0900 Subject: [PATCH 5/5] add: document GitHub teams and their responsibilities in CONTRIBUTING.md --- CONTRIBUTING.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f582c42..073d1a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -640,6 +640,23 @@ follow strict review ownership and merge rules: > 2. Pass all automated CI/CD checks (formatting, compilation across supported platforms, and unit tests). > 3. Resolve all open review discussions and inline thread feedback. +#### Github Teams + + +| | Team | Responsibilities | +| --- | --- | ---------------- | +| ![](https://avatars.githubusercontent.com/t/18658494?s=116) | Security | Safeguards cloud execution environments, protects user data and proprietary engine assets, and manages platform access controls and vulnerability management. | +| ![](https://avatars.githubusercontent.com/t/18658514?s=116) | QA & Test Infrastructure | Develops automated testing pipelines, continuous integration workflows, and quality assurance suites across platform and engine releases. | +| ![](https://avatars.githubusercontent.com/t/18658503?s=116) | Legal & Compliance | Oversees terms of service, IP licensing agreements, NDA enforcement, platform partner compliance, and regulatory standards. | +| ![](https://avatars.githubusercontent.com/t/16191538?s=116) | Infrastructure & DevOps | Manages cloud infrastructure, remote GPU execution, deployment pipelines, and system scalability for the platform. | +| ![](https://avatars.githubusercontent.com/t/16191529?s=116) | Graphics Engineering | Implements graphics algorithms, shaders, and real-time rendering systems used across the learning engine and experimental modules. | +| ![](https://avatars.githubusercontent.com/t/16191525?s=116) | Engine Architecture | Designs and maintains the core graphics engine, including rendering pipelines, GPU abstractions, and low-level engine architecture. | +| ![](https://avatars.githubusercontent.com/t/16191540?s=116) | Documentation & Knowledge | Maintains technical documentation, contributor guidelines, and educational references across the Graphical Playground ecosystem. | +| ![](https://avatars.githubusercontent.com/t/18658516?s=116) | Data & Analytics | Tracks, models, and analyzes user learning behaviors, platform performance telemetry, and key growth metrics to guide product decisions. | +| ![](https://avatars.githubusercontent.com/t/16191539?s=116) | Curriculum & Learning Design | Defines learning paths, educational structure, and progression across courses, sample projects, and certification programs. | +| ![](https://avatars.githubusercontent.com/t/18658540?s=116) | Community & DevRel | Fosters developer engagement, manages community forums and events, and advocates for user and contributor needs across the platform ecosystem. | + + ## Coding Standards For a project of this scale, maintaining a consistent coding style is crucial for readability,