docs: Add information around smoke tests

Author: deadlydog

deploy/Invoke-SmokeTests.ps1

@@ -2,6 +2,7 @@
 # These tests run against the installed module, not the source code, so they are a real-world test and should not use mocks.
 # Since mocks are not used, be careful to not rely on state stored on the machine, such as a module configuration file.
 # This is a great place to put tests that differ between operating systems, since they will be ran on multiple platforms.
+# Keep in mind that these tests can only call the public functions in the module, not the private functions.
 # To run these tests on your local machine, see the comments in the BeforeAll block.
 
 BeforeAll {

docs/Contributing.md

@@ -23,12 +23,21 @@ If you want to increment the Major or Minor version number, you have 2 options:
    Builds are not triggered on tags, and thus the version tag will be used as the starting point for the next version.
    e.g. Creating a new tag of `v2.4.0` will produce a new version of `2.4.1` on the next commit to the `main` branch.
 
-## Why are the template dot-files filenames prefixed with an underscore?
+## 📄 Why are the template dot-files filenames prefixed with an underscore?
 
 `Publish-Module` has a bug where it does not include any files or directories starting with `.` in the module NuGet package.
 The newer `Publish-PSResource` has fixed this issue somewhat so the directories and some of the files are included, but it still leaves out some dot-files, like the `.gitignore` and `.editorconfig` files.
 To work around these issues, we prefix the files with an underscore (e.g. `_.gitignore`) so that they are included in the module package, and then remove the underscore prefix during the file copy process of the `New-PowerShellScriptModuleRepository` cmdlet.
 
+## 🧪 Smoke tests
+
+[The Smoke tests](/deploy/Invoke-SmokeTests.ps1) are used during the CI/CD workflow to verify that the module is working as expected after it is published to the gallery.
+The smoke tests are ran on Windows, MacOS, and Linux agents to ensure cross-platform compatibility, as well as against a Windows PowerShell 5.1 agent to ensure backward compatibility.
+
+The difference between the smoke tests and the regular tests is that the smoke tests rely on the module actually being installed, not just the files being present.
+This means they can only test the functions and aliases that are exported from the module manifest and publicly accessible.
+This is the reason why we must use different files for the smoke tests than the regular tests; regular tests can test private functions and variables, but smoke tests cannot.
+
 ## ⁉ Why was a specific decision made
 
 Curious about some of the choices made in this project?

src/ScriptModuleRepositoryTemplate/TemplateRepoFiles/ReadMe.md

@@ -21,6 +21,11 @@ If you already have the module, manifest, and tests written, replace the followi
 
 Otherwise, use these files as a starting point for your new module.
 
+#### Smoke tests
+
+When you change the module and tests, you will also need to update [the Smoke tests](/deploy/Invoke-SmokeTests.ps1), otherwise they may fail the CI/CD workflow.
+See the [Contributing docs](/docs/Contributing.md) for more information on smoke tests.
+
 ### 🚀 Step 4: Update your CI/CD workflows
 
 #### 🔑 Create a PowerShell Gallery API Key

src/ScriptModuleRepositoryTemplate/TemplateRepoFiles/deploy/Invoke-SmokeTests.ps1

@@ -2,6 +2,7 @@
 # These tests run against the installed module, not the source code, so they are a real-world test and should not use mocks.
 # Since mocks are not used, be careful to not rely on state stored on the machine, such as a module configuration file.
 # This is a great place to put tests that differ between operating systems, since they will be ran on multiple platforms.
+# Keep in mind that these tests can only call the public functions in the module, not the private functions.
 # To run these tests on your local machine, see the comments in the BeforeAll block.
 
 BeforeAll {

src/ScriptModuleRepositoryTemplate/TemplateRepoFiles/docs/Contributing.md

@@ -19,3 +19,16 @@ If you want to increment the Major or Minor version number, you have 2 options:
 1. Create a new version tag and pushing it up to GitHub.
    Builds are not triggered on tags, and thus the version tag will be used as the starting point for the next version.
    e.g. Creating a new tag of `v2.4.0` will produce a new version of `2.4.1` on the next commit to the `main` branch.
+
+## 🧪 Smoke tests
+
+[The Smoke tests](/deploy/Invoke-SmokeTests.ps1) are used during the CI/CD workflow to verify that the module is working as expected after it is published to the gallery.
+The smoke tests are ran on Windows, MacOS, and Linux agents to ensure cross-platform compatibility, as well as against a Windows PowerShell 5.1 agent to ensure backward compatibility.
+
+The difference between the smoke tests and the regular tests is that the smoke tests rely on the module actually being installed, not just the files being present.
+This means they can only test the functions and aliases that are exported from the module manifest and publicly accessible.
+This is the reason why we must use different files for the smoke tests than the regular tests; regular tests can test private functions and variables, but smoke tests cannot.
+
+You do not need to run every public function test in the smoke tests, but it can help give you confidence that the module is truly cross-platform and backward compatible.
+If you do not want to run any smoke tests, you can comment out all of the code in the smoke tests file.
+The CI/CD workflow will still validate that the module can be installed on each platform.