From e0d74b87710152ac9478f7870872d9c60cf2ad17 Mon Sep 17 00:00:00 2001
From: Michael T Lombardi <michael.t.lombardi@gmail.com>
Date: Thu, 3 Jun 2021 13:23:29 -0500
Subject: [PATCH] (GH-150) Add known installation limitations to readme

This commit adds the existing limitations for installing DSC modules with
long file paths for r10k and serverless Puppet users, including links to
the issues that need to be addressed.

- Resolves #150
---
 CHANGELOG.md                                 |  3 ++-
 src/internal/functions/Get-ReadmeContent.ps1 | 23 ++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 497a9fcd..210fffa6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,12 +12,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ability to set generated modules fixtures to something other than the latest released version of `puppetlabs-pwshlib` on the Forge ([#93](https://github.com/puppetlabs/Puppet.Dsc/issues/93))
 - A check to `New-PuppetDscModule` which validates that PSRemoting is enabled and errors clearly if not in order to prevent unexpected execution failures later in the process ([#133](https://github.com/puppetlabs/Puppet.Dsc/issues/133))
 - Long file path support information to the requirements section of autogenerated READMEs ([#149](https://github.com/puppetlabs/Puppet.Dsc/issues/149))
+- Notes on installation limitations to generated README files to clarify minitar limitations for `r10k` and serverless Puppet users ([#150](https://github.com/puppetlabs/Puppet.Dsc/issues/150))
 
 ### Fixed
 
 - Ensure that the auto-generated readme of a Puppetized module contains both the PowerShell and Puppet module names ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
 - Make all `Update-PuppetModuleReadme` parameters except `PuppetModuleName` mandatory and do not accept null or empty values ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
-- Make the  `PowerShellModuleName` and `PuppetModuleName` parameters in `Get-Readmecontent` mandatory and do not accept null or empty values for any parameters ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
+- Make the `PowerShellModuleName` and `PuppetModuleName` parameters in `Get-Readmecontent` mandatory and do not accept null or empty values for any parameters ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
 
 ## [0.5.0] - 2021-2-10
 
diff --git a/src/internal/functions/Get-ReadmeContent.ps1 b/src/internal/functions/Get-ReadmeContent.ps1
index 8d047260..106f0b94 100644
--- a/src/internal/functions/Get-ReadmeContent.ps1
+++ b/src/internal/functions/Get-ReadmeContent.ps1
@@ -52,6 +52,8 @@ function Get-ReadmeContent {
     $NarrativeDocumentation       = 'https://puppetlabs.github.io/iac/news/roadmap/2020/03/30/dsc-announcement.html'
     $TroubleshootingDocumentation = 'https://github.com/puppetlabs/Puppet.Dsc#troubleshooting'
     $MicrosoftLongPathSupportDocs = 'https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell#enable-long-paths-in-windows-10-version-1607-and-later'
+    $PuppetModuleInstallIssue     = 'https://tickets.puppetlabs.com/browse/PUP-10924'
+    $r10kInstallationIssue        = 'https://github.com/puppetlabs/r10k/issues/1117'
   }
 
   Process {
@@ -234,6 +236,27 @@ For specific information on troubleshooting a generated module, check the [troub
 
 Currently, because of the way Puppet caches files on agents, use of the legacy [``puppetlabs-dsc``]($LegacyDscForgePage) module is **not** compatible with this or any auto-generated DSC module.
 Inclusion of both will lead to pluginsync conflicts.
+
+### Module Installation
+
+If you're using this module with Puppet Enterprise and Code Manager, everything should "just work" - no errors or issues acquiring and deploying this or any Puppetized DSC module to nodes.
+
+Unfortunately, due a bug in minitar which prevents it from unpacking archives with long file paths, both [``r10k``]($r10kInstallationIssue) and [serverless Puppet (via ``puppet module install``)]($PuppetModuleInstallIssue) methods of installing modules with long path names will fail.
+In short, minitar is unable to unpack modules that contain long file paths (though it can create them).
+
+As a workaround, you can retrieve DSC modules from the forge via PowerShell and 7zip:
+
+``````powershell
+`$ModuleAuthor = 'dsc'
+`$ModuleName = 'xremotedesktopsessionhost'
+`$ModuleVersion = '2.0.0-0-1'
+`$ArchiveFileName = "`$ModuleAuthor-`$ModuleName-`$ModuleVersion.tar.gz"
+`$DownloadUri = "https://forge.puppet.com/v3/files/`$ArchiveFileName"
+# Download the module tar.gz to the current directory
+Invoke-WebRequest -Uri `$DownloadUri -OutFile ./`$ArchiveFileName
+# Use 7zip to extract the module to the current directory
+& 7z x `$ArchiveFileName -so | & 7z x -aoa -si -ttar
+``````
 "@
   }