From 19bee10f42a1d07c07a59f73d55c753e35ec88a9 Mon Sep 17 00:00:00 2001
From: Leander Schulten <Leander.Schulten@rwth-aachen.de>
Date: Tue, 11 Apr 2023 17:27:55 +0200
Subject: [PATCH] Add docs for the new ways to report build failures and giving
 hint messages from portfile.cmake

---
 vcpkg/TOC.yml                                 |  4 +++
 ...pkg_fail_with_user_interaction_required.md | 27 +++++++++++++++++++
 .../functions/vcpkg_user_hint_on_failure.md   | 27 +++++++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 vcpkg/maintainers/functions/vcpkg_fail_with_user_interaction_required.md
 create mode 100644 vcpkg/maintainers/functions/vcpkg_user_hint_on_failure.md

diff --git a/vcpkg/TOC.yml b/vcpkg/TOC.yml
index a523278c..01f77ae2 100644
--- a/vcpkg/TOC.yml
+++ b/vcpkg/TOC.yml
@@ -148,6 +148,8 @@
       href: maintainers/functions/vcpkg_extract_source_archive.md
     - name: vcpkg_extract_source_archive_ex
       href: maintainers/functions/vcpkg_extract_source_archive_ex.md
+    - name: vcpkg_fail_with_user_interaction_required
+      href: maintainers/functions/vcpkg_fail_with_user_interaction_required.md
     - name: vcpkg_fail_port_install
       href: maintainers/functions/vcpkg_fail_port_install.md
     - name: vcpkg_find_acquire_program
@@ -212,6 +214,8 @@
       href: maintainers/functions/vcpkg_replace_string.md
     - name: vcpkg_restore_env_variables
       href: maintainers/functions/vcpkg_restore_env_variables.md
+    - name: vcpkg_user_hint_on_failure
+      href: maintainers/functions/vcpkg_user_hint_on_failure.md
     - name: Internal
       items:
       - name: z_vcpkg_apply_patches
diff --git a/vcpkg/maintainers/functions/vcpkg_fail_with_user_interaction_required.md b/vcpkg/maintainers/functions/vcpkg_fail_with_user_interaction_required.md
new file mode 100644
index 00000000..ce4259db
--- /dev/null
+++ b/vcpkg/maintainers/functions/vcpkg_fail_with_user_interaction_required.md
@@ -0,0 +1,27 @@
+---
+title: vcpkg_fail_with_user_interaction_required
+description: Learn how to use vcpkg_fail_with_user_interaction_required.
+ms.date: 04/11/2023
+---
+# vcpkg_fail_with_user_interaction_required
+
+Outputs the message to the console and stops the execution of the `portfile.cmake`. 
+
+In comparison to `message(FATAL_ERROR <message>)` vcpkg don't emit instructions on how to report an issue and the `<message>` is printed instead. 
+
+## Usage
+
+```cmake
+vcpkg_fail_with_user_interaction_required(<message>)
+```
+
+## Parameters
+
+### `<message>`
+
+The error message that should be displayed to the user.
+
+## Source
+
+[scripts/cmake/vcpkg\_fail\_with\_user\_interaction\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_with_user_interaction_required.cmake)
+
diff --git a/vcpkg/maintainers/functions/vcpkg_user_hint_on_failure.md b/vcpkg/maintainers/functions/vcpkg_user_hint_on_failure.md
new file mode 100644
index 00000000..de763919
--- /dev/null
+++ b/vcpkg/maintainers/functions/vcpkg_user_hint_on_failure.md
@@ -0,0 +1,27 @@
+---
+title: vcpkg_user_hint_on_failure
+description: Learn how to use vcpkg_user_hint_on_failure.
+ms.date: 04/11/2023
+---
+# vcpkg_user_hint_on_failure
+
+Outputs the message to the console if the building of the port fails.
+
+The message is emitted after the instructions on how to report an issue as an hint how to resolve the build failure.
+
+## Usage
+
+```cmake
+vcpkg_user_hint_on_failure(<message>)
+```
+
+## Parameters
+
+### `<message>`
+
+The hint message that should be displayed to the user if case of an build failure.
+
+## Source
+
+[scripts/cmake/vcpkg\_user\_hint\_on\_failure.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_user_hint_on_failure.cmake)
+