Merge pull request #6378 from Calinou/improve-bisecting-regressions

Improve the Bisecting regressions page

community/contributing/bisecting_regressions.rst

@@ -32,20 +32,27 @@ range of commits that potentially need to be built from source and tested.
 You can find binaries of official releases, as well as alphas, betas,
 and release candidates `here <https://downloads.tuxfamily.org/godotengine/>`__.
 
-For example, if you've reported a bug against Godot 3.2, you should first try to
-reproduce the bug in Godot 3.1 (not a patch release, see below for the reason).
-If the bug doesn't occur there, try to reproduce it in Godot 3.2 *beta 1* (which
-is roughly in the middle of all test builds available). If you can't reproduce
-the bug with Godot 3.2 beta 1, then try newer betas and RC builds. If you do
-manage to reproduce the bug with Godot 3.2 beta 1, then try older alpha builds.
+If you have experience with Godot 3.x and can reproduce an issue with Godot 4.0,
+we recommend trying to reproduce the issue in the latest Godot 3.x version (if
+the feature exhibiting the bug is present in 3.x). This can be used to check
+whether the issue is a regression in 4.0 or not.
+
+- If the issue **is present** in 3.x, then you'll need to check whether the issue
+  occurs in older 3.x versions as well.
+- If the issue is **not present** in 3.x, then you can try older 4.0 alphas and
+  betas to determine when the regression started.
 
 .. warning::
 
-    For bisecting regressions, don't use patch releases such as Godot 3.1.2.
-    Instead, use the minor version's first release like Godot 3.1. This is
-    because patch releases are built from a separate *stable branch*. This kind
-    of branch doesn't follow the rest of Godot's development, which is done in
-    the ``master`` branch.
+    Project files may be incompatible between Godot versions.
+    **Make a backup of your project** before starting the bisection process.
+
+    Going from the oldest to the newest build generally reduces the risk of the
+    project not being able to successfully open in the editor, thanks to
+    backwards compatibility. Try to reduce your project to the smallest
+    repeatable example too. The more minimal the project is, the more likely
+    you'll be able to open it without compatibility issues in newer engine
+    versions.
 
 The Git bisect command
 ----------------------
@@ -69,6 +76,9 @@ reproduce the bug.
     there and report the results of your "pre-bisecting" on the GitHub issue so
     another contributor can continue bisecting from there.
 
+Determine the commit hashes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 To start bisecting, you must first determine the commit hashes (identifiers) of
 the "bad" and "good" build. "bad" refers to the build that exhibits the bug,
 whereas "good" refers to the version that doesn't exhibit the bug. If you're
@@ -82,12 +92,46 @@ following commit hashes depending on the version:
 
 .. code-block:: none
 
+    3.5.1-stable
+    3.5-stable
+    3.4.5-stable
+    3.4.4-stable
+    3.4.3-stable
+    3.4.2-stable
+    3.4.1-stable
+    3.4-stable
+    3.3.4-stable
+    3.3.3-stable
+    3.3.2-stable
+    3.3.1-stable
+    3.3-stable
     3.2-stable
     3.1-stable
     3.0-stable
 
+You can also use this Bash function to retrieve the Git commit hash of a
+pre-release build (add it to your ``$HOME/.bashrc`` or similar):
+
+::
+
+    gd_snapshot_commit() {
+        curl -s https://downloads.tuxfamily.org/godotengine/$1/$2/README.txt \
+            | grep 'from commit' \
+            | sed 's/^Built from commit \(.*\)\.$/\1/'
+    }
+
+Example usage:
+
+.. code-block:: shell
+
+    $ gd_snapshot_commit 4.0 beta4
+
 To refer to the latest state of the master branch, you can use ``master``
-instead of a commit hash.
+instead of a commit hash. Note that unlike tagged releases or snapshot commit
+hashes, ``master`` is a perpetually moving target.
+
+Build the engine
+^^^^^^^^^^^^^^^^
 
 :ref:`Get Godot's source code using Git <doc_getting_source>`. Once this
 is done, in the terminal window, use ``cd`` to reach the Godot repository
@@ -105,16 +149,19 @@ Compile Godot. This assumes you've set up a build environment:
 
 .. code-block:: shell
 
-    # <platform> is the platform you're targeting for regression testing,
-    # like "windows", "x11" or "macos".
-    $ scons platform=<platform> -j4
+    $ scons
 
-Since building Godot takes a while, you want to dedicate as many CPU threads as
-possible to the task. This is what the ``-j`` parameter does. Here, the command
-assigns 4 CPU threads to compiling Godot.
+Run the engine
+^^^^^^^^^^^^^^
 
 Run the binary located in the ``bin/`` folder and try to reproduce the bug.
 
+.. note::
+
+    :ref:`Double-check the output file name <doc_introduction_to_the_buildsystem_resulting_binary>`
+    in ``bin/`` to make sure you're actually running the binary you've just compiled.
+    Different Godot versions will output binaries with different names.
+
 If the build **still** exhibits the bug, run the following command:
 
 .. code-block:: shell

development/compiling/introduction_to_the_buildsystem.rst

@@ -92,6 +92,8 @@ Example for using 4 cores:
 
     scons platform=linuxbsd -j 4
 
+.. _doc_introduction_to_the_buildsystem_resulting_binary:
+
 Resulting binary
 ----------------