Document the hashing logic (#6220)

* Document the hashing logic

* Update docs/docs/cloud/hashing.md

Co-authored-by: Marek Fořt <marekfort@me.com>

* Update docs/docs/cloud/hashing.md

Co-authored-by: Marek Fořt <marekfort@me.com>

---------

Co-authored-by: Marek Fořt <marekfort@me.com>

docs/.vitepress/config.mjs

@@ -262,6 +262,10 @@ export default defineConfig({
               text: "Selective testing",
               link: "/cloud/selective-testing",
             },
+            {
+              text: "Hashing",
+              link: "/cloud/hashing",
+            },
             {
               text: "On-premise",
               link: "/cloud/on-premise",

docs/docs/cloud/hashing.md

@@ -0,0 +1,38 @@
+---
+title: Hashing
+description: Learn about Tuist's hashing logic upon which features like binary caching and selective testing are built.
+---
+
+# Hashing
+
+To determine if a target has changed, Tuist **calculates a hash for each target** in the dependency graph. [Binary caching](/cloud/binary-caching) leverages that information to determine whether binaries should be used for a particular target, or if the tests of a target should be run. The hash is calculated based on the following attributes:
+
+- The target's attributes (e.g., name, platform, product, etc.)
+- The target's files
+- The hash of the target's dependencies
+
+### Binary caching
+
+Additionally, when calculating the hash for [binary caching](/cloud/binary-caching), we also hash the following attributes.
+
+#### Swift version
+
+We hash the Swift version obtained from running the command `/usr/bin/xcrun swift --version` to prevent compilation errors due to Swift version mismatches between the targets and the binaries.
+
+> [!NOTE] MODULE STABILITY
+> Previous versions of binary caching relied on the `BUILD_LIBRARY_FOR_DISTRIBUTION` build setting to enable [module stability](https://www.swift.org/blog/library-evolution#enabling-library-evolution-support) and enable using binaries with any compiler version. However, it caused compilation issues in projects with targets that don't support module stability. Generated binaries are bound to the Swift version used to compile them, and the Swift version must match the one used to compile the project.
+
+#### Configuration
+
+
+The idea behind this flag was to ensure debug binaries were not used in release builds and viceversa. However, we are still missing a mechanism to remove the other configurations from the projects to prevent them from being used.
+
+## Debugging
+
+If you notice non-deterministic behaviors when using the caching across environments or invocations, it might be related to differences across the environments or a bug in the hashing logic. We recommend following these steps to debug the issue:
+
+1. Ensure the same [configuration](#configuration) and [Swift version](#swift-version) is used across environments. 
+2. Check if there are differences between the Xcode projects generated by two consecutive invocations of `tuist generate` or across environments. You can use the `diff` command to compare the projects. The generated projects might include **absolute paths** causing the hashing logic to be non-deterministic.
+
+> [!NOTE] BETTER DEBUGGING EXPERIENCE PLANNED
+> Improving our debugging experience is in our roadmap. The print-hashes command, which lacks the context to understand the differences, will be replaced by a more user-friendly command that uses a tree-like structure to show the differences between the hashes.