From b167b99931542f5a778b9c05f8f17b4c0c749c47 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Wed, 8 Dec 2021 18:39:08 +0100
Subject: [PATCH] Add a guide on contributing new benchmarks

---
 CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++
 LICENSE.md      |  6 ++--
 README.md       |  7 ++++-
 3 files changed, 85 insertions(+), 3 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..aa502ac
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing to godot-benchmarks
+
+Thank you for your interest in contributing!
+
+**Note:** This project only supports Godot's `master` branch (4.0's development
+branch), not Godot 3.x. Attempting to open this project in Godot 3.x will result
+in errors.
+
+## Adding new benchmarks
+
+You can add new test cases by following these steps:
+
+### Create new benchmark
+
+- Open the Godot editor and import this project.
+- Create a new scene with `snake_case` naming with a root node suited to the
+  benchmark[^1], then save it in one of the existing folders depending on its
+  category. If your benchmark does not suit any existing category or
+  subcategory, you can also create a new folder in the repository's root folder.
+  The root node's name does not have any bearing on functionality, but it's
+  recommended to use a PascalCase version of the scene name. For example, if
+  your scene file name is `typed_int_array.tscn`, the root node name should be
+  `TypedIntArray`.
+
+[^1]: For 3D rendering benchmarks, the root node should be Node3D. For 2D
+rendering benchmarks, the root node should be Node2D. For UI benchmarks, the
+root node should be Control. For scripting or miscellaneous benchmarks, the root
+node should be Node.
+
+### Configure the benchmark
+
+- Create a Label node, rename it to `Benchmark` (case-sensitive) and attach
+  `benchmark.gd` as a script. Select the Benchmark node to configure its
+  properties. There are 5 properties available which control the *metrics* that
+  will be displayed in the results table:
+  - **Test Render Cpu:** Enable this for rendering benchmarks. Leave it disabled
+    for other benchmarks.
+  - **Test Render Gpu:** Enable this for rendering benchmarks. Leave it disabled
+    for other benchmarks.
+  - **Test Idle:** Enable this for non-rendering CPU-intensive benchmarks. Leave
+    it disabled for other benchmarks.
+  - **Test Physics:** Enable this for physics benchmarks. Leave it disabled for
+    other benchmarks.
+  - **Time Limit:** Enable this for rendering or physics benchmarks (which
+    measure the time spent processing things every frame instead of a total time
+    to process a set amount of items). For other benchmarks such as scripting,
+    disable this.
+- Attach a script to the scene's root node, with the same name as the scene file
+  (except the file extension will be `.gd` instead of `.tscn`). In the script's
+  `_ready()` function, perform the benchmark tasks. You don't need to surround
+  the benchmarked code with time measurement functions, as time is measured
+  automatically.
+- For benchmarks that do not have a fixed time limit (such as scripting benchmarks),
+  call `Manager.end_test()` at the end of the `_ready()` function.
+- Modify `manager.gd` in the repository root to include your new benchmark
+  (`tests` array variable). The new benchmark should be listed at the bottom of
+  the category it was added to. For clarity, make sure to separate each category
+  with a blank line within the `tests` array.
+
+Remember to follow the
+[GDScript style guide](https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_styleguide.html)
+when writing new scripts. Adding type hints is recommended whenever possible,
+unless you are specifically benchmarking non-typed scripts.
+
+### Test the benchmark
+
+- Run the project in the editor.
+- Check the checkbox next to your newly added benchmark and click **Run** in the
+  bottom-right corner.
+- Wait for the benchmark to complete.
+- If all goes well, the benchmark completion time should appear in the table for
+  all enabled benchmarks (and all relevant metrics). Metrics that were disabled
+  on a specific benchmarks will not display any result.
+
+If the benchmark works as expected, congratulations! You can now open a pull request for it :)
diff --git a/LICENSE.md b/LICENSE.md
index 9710bc1..d3d131f 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,5 +1,7 @@
-Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. \
-Copyright (c) 2014-2020 Godot Engine contributors.
+# MIT License
+
+Copyright (c) 2007-2021 Juan Linietsky, Ariel Manzur.
+Copyright (c) 2014-2021 Godot Engine contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
diff --git a/README.md b/README.md
index 1587009..00ac25c 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,7 @@
 # godot-benchmarks
-Collection of benchmarks to test performance of different areas of Godot
+
+This is a Godot project that stores and runs a collection of benchmarks. It is
+used to test performance of different areas of [Godot](https://godotengine.org)
+such as rendering and scripting.
+
+**Interested in adding new benchmarks?** See [CONTRIBUTING.md](CONTRIBUTING.md).