From 748c7e542019b19f2c9e38dd37c85aeb17402a3a Mon Sep 17 00:00:00 2001
From: Tamara Dahlgren <35777542+tldahlgren@users.noreply.github.com>
Date: Tue, 1 Apr 2025 00:02:50 -0700
Subject: [PATCH] Documentation: remote URL inclusion updates (#49669)

---
 lib/spack/docs/environments.rst |  7 ++++---
 lib/spack/docs/include_yaml.rst | 14 ++++++++++++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/lib/spack/docs/environments.rst b/lib/spack/docs/environments.rst
index 3221fc58e02..eb50ec6ae4f 100644
--- a/lib/spack/docs/environments.rst
+++ b/lib/spack/docs/environments.rst
@@ -686,7 +686,8 @@ the environment.
    spack:
      include:
      - environment/relative/path/to/config.yaml
-     - https://github.com/path/to/raw/config/packages.yaml
+     - path: https://github.com/path/to/raw/config/compilers.yaml
+       sha256: 26e871804a92cd07bb3d611b31b4156ae93d35b6a6d6e0ef3a67871fcb1d258b
      - /absolute/path/to/packages.yaml
      - path: /path/to/$os/$target/environment
        optional: true
@@ -700,11 +701,11 @@ with the ``optional`` clause and conditional with the ``when`` clause. (See
 
 Files are listed using paths to individual files or directories containing them.
 Path entries may be absolute or relative to the environment or specified as 
-URLs. URLs to individual files need link to the **raw** form of the file's 
+URLs. URLs to individual files must link to the **raw** form of the file's 
 contents (e.g., `GitHub
 <https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#viewing-or-copying-the-raw-file-content>`_ 
 or `GitLab
-<https://docs.gitlab.com/ee/api/repository_files.html#get-raw-file-from-repository>`_).
+<https://docs.gitlab.com/ee/api/repository_files.html#get-raw-file-from-repository>`_) **and** include a valid sha256 for the file.
 Only the ``file``, ``ftp``, ``http`` and ``https`` protocols (or schemes) are
 supported. Spack-specific, environment and user path variables can be used.
 (See :ref:`config-file-variables` for more information.)
diff --git a/lib/spack/docs/include_yaml.rst b/lib/spack/docs/include_yaml.rst
index 30beb067b94..826f976bddc 100644
--- a/lib/spack/docs/include_yaml.rst
+++ b/lib/spack/docs/include_yaml.rst
@@ -43,6 +43,20 @@ or specified as URLs. Only the ``file``, ``ftp``, ``http`` and ``https`` protoco
 schemes) are supported. Spack-specific, environment and user path variables
 can be used. (See :ref:`config-file-variables` for more information.)
 
+A ``sha256`` is required for remote file URLs and must be specified as follows:
+
+.. code-block:: yaml
+
+   include:
+   - path: https://github.com/path/to/raw/config/compilers.yaml
+     sha256: 26e871804a92cd07bb3d611b31b4156ae93d35b6a6d6e0ef3a67871fcb1d258b
+
+Additionally, remote file URLs must link to the **raw** form of the file's
+contents (e.g., `GitHub
+<https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#viewing-or-copying-the-raw-file-content>`_
+or `GitLab
+<https://docs.gitlab.com/ee/api/repository_files.html#get-raw-file-from-repository>`_).
+
 .. warning::
 
    Recursive includes are not currently processed in a breadth-first manner