update docs on how to deal with breaking changes to the build system

build.zig

@@ -17,7 +17,8 @@ const minimum_build_zig_version = "0.13.0";
 /// Examples of reasons that would cause the minimum runtime version to be bumped are:
 ///   - breaking change to the Zig Syntax
 ///   - breaking change to AstGen (i.e `zig ast-check`)
-///   - breaking change to the build system (see `src/build_runner`)
+///
+/// A breaking change to the Zig Build System should be handled by updating ZLS's build runner (see src\build_runner)
 const minimum_runtime_zig_version = "0.12.0";
 
 const release_targets = [_]std.Target.Query{

src/build_runner/0.12.0.zig

@@ -1,5 +1,12 @@
 //! PLEASE READ THE FOLLOWING MESSAGE BEFORE EDITING THIS FILE:
-//! Update the `minimum_runtime_zig_version` field in `build.zig` a breaking change occured.
+//!
+//! This build runner is targeting compatibility with the following Zig versions:
+//!   - Zig 0.12.0
+//!   - Zig 0.13.0
+//!   - master
+//!
+//! Handling multiple Zig versions can be achieved by branching on the `builtin.zig_version` at comptime.
+//! As an example, see how `writeFile2_removed_version` or `std_progress_rework_version` are used to deal with breaking changes.
 //!
 //! You can test out the build runner on ZLS's `build.zig` with the following command:
 //! `zig build --build-runner src/build_runner/0.12.0.zig`
@@ -8,7 +15,6 @@
 //! `zig build --build-file /path/to/build.zig --build-runner /path/to/zls/src/build_runner/0.12.0.zig`
 //! `zig build --build-runner /path/to/zls/src/build_runner/0.12.0.zig` (if the cwd contains build.zig)
 //!
-//! This build runner is also compatible with Zig 0.13.0
 
 const root = @import("@build");
 const std = @import("std");
@@ -21,11 +27,15 @@ const Step = std.Build.Step;
 
 pub const dependencies = @import("@dependencies");
 
+// ----------- List of Zig versions that introduced breaking changes -----------
+
 const writeFile2_removed_version =
     std.SemanticVersion.parse("0.13.0-dev.68+b86c4bde6") catch unreachable;
 const std_progress_rework_version =
     std.SemanticVersion.parse("0.13.0-dev.336+963ffe9d5") catch unreachable;
 
+// -----------------------------------------------------------------------------
+
 const ProgressNode = if (builtin.zig_version.order(std_progress_rework_version) == .lt)
     *std.Progress.Node
 else

src/build_runner/BuildRunnerVersion.zig

@@ -1,8 +1,12 @@
 const std = @import("std");
 const build_options = @import("build_options");
 
-// These versions must be ordered from newest to oldest.
-// There should be no need to have a build runner for minor patches (e.g. 0.10.1)
+/// These versions must be ordered from newest to oldest.
+/// There should be no need to have a build runner for minor patches (e.g. 0.10.1)
+///
+/// A "master" build runner should only be added if it is infeasible to make the latest build runner compatible with Zig master.
+///
+/// The GitHub matrix in `.github\workflows\build_runner.yml` should be updated to check Zig master with the latest build runner file.
 pub const BuildRunnerVersion = enum {
     // master,
     @"0.13.0",