flushed out more thoughts on the topic

KirkMunro · KirkMunro · commit d14daf7366e0 · 2019-06-11T12:38:39.000-03:00
diff --git a/1-Draft/RFCNNNN-Simplify-Module-Manifests.md b/1-Draft/RFCNNNN-Simplify-Module-Manifests.md
@@ -44,17 +44,20 @@ Beyond PowerShell 3.0, keys started being added to a `PSData` subsection of the
 
 Fast forward to today, and things have changed enough that we can reconsider how we set up a module manifest. `Import-Module` has been checking the required version of PowerShell before validating key names for several years now, at least since PowerShell 5.1, and earlier versions of Windows PowerShell are no longer on mainstream support.
 
-With all of this in mind, this proposal is to flatten the module manifest structure, reading values for keys at the root first, and then if they are not set at the root, looking in the `PSData` section under `PrivateData` for backwards compatibility support. Future keys added to the manifest as part of PowerShell should all be added to the root, leaving `PrivateData` for 3rd party or user information in a manifest, as originally intended.
+With all of this in mind, this proposal is to accomplish two things:
+
+1. To flatten the module manifest structure for the current version of PowerShell (whichever version this gets implemented in), reading values for keys at the root first, and then if they are not set at the root, looking in the `PSData` section under `PrivateData` for backwards compatibility support. Future keys added to the manifest as part of PowerShell should all be added to the root, leaving `PrivateData` for 3rd party or user information in a manifest, as originally intended.
+1. To make the current version of PowerShell a default value for `-PowerShellVersion`, and update `New-ModuleManifest` such that it generates an appropriate manifest for the version of PowerShell indicated in the `-PowerShellVersion` parameter, so that scripters can create manifests for modules on newer versions of PowerShell that are properly structured to support older versions of PowerShell as well.
 
 ## Motivation
 
     As a scripter,
-    I can generate manifests using `New-ModuleManifest` with all keys stored at the root of the hashtable,
-    so that I can work with module manifests more easily.
+    I can generate manifests using `New-ModuleManifest` for any supported version of PowerShell,
+    so that I can work with module manifests more easily in the current version without letting go of compatibilty support for downlevel versions.
 
 ## User Experience
 
-Here's an example showing how `New-ModuleManifest` would work after this change:
+Here's an example showing how `New-ModuleManifest` would work with the default value of `-PowerShellVersion` after this change:
 
 ```powershell
 New-ModuleManifest .\test.psd1 -PassThru | Get-Content
@@ -96,7 +99,7 @@ Copyright = '(c) 2019 kirka. All rights reserved.'
 # Description = ''
 
 # Minimum version of the Windows PowerShell engine required by this module
-# PowerShellVersion = ''
+PowerShellVersion = '7.0'
 
 # Name of the Windows PowerShell host required by this module
 # PowerShellHostName = ''
@@ -152,12 +155,9 @@ AliasesToExport = @()
 # List of all files packaged with this module
 # FileList = @()
 
-# Private data to pass to the module specified in RootModule/ModuleToProcess.
+# Private data to pass to the module specified in RootModule.
 PrivateData = @{}
 
-# HelpInfo URI of this module
-# HelpInfoURI = ''
-
 # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
 # DefaultCommandPrefix = ''
 
@@ -182,17 +182,147 @@ PrivateData = @{}
 }
 ```
 
+Here's an example showing how `New-ModuleManifest` would work with the a specific `-PowerShellVersion` after this change:
+
+```powershell
+New-ModuleManifest .\test.psd1 -PowerShellVersion 2 -PassThru | Get-Content
+```
+
+```output
+#
+# Module manifest for module 'test'
+#
+# Generated by: kirka
+#
+# Generated on: 2019-06-09
+#
+
+@{
+
+# Script module or binary module file associated with this manifest.
+# ModuleToProcess = ''
+
+# Version number of this module.
+ModuleVersion = '1.0'
+
+# ID used to uniquely identify this module
+GUID = '47179120-0bcb-4f14-8d80-f4560107f85c'
+
+# Author of this module
+Author = 'kirka'
+
+# Company or vendor of this module
+CompanyName = 'Unknown'
+
+# Copyright statement for this module
+Copyright = '(c) 2019 kirka. All rights reserved.'
+
+# Description of the functionality provided by this module
+# Description = ''
+
+# Minimum version of the Windows PowerShell engine required by this module
+PowerShellVersion = '2.0'
+
+# Name of the Windows PowerShell host required by this module
+# PowerShellHostName = ''
+
+# Minimum version of the Windows PowerShell host required by this module
+# PowerShellHostVersion = ''
+
+# Minimum version of the .NET Framework required by this module
+# DotNetFrameworkVersion = ''
+
+# Minimum version of the common language runtime (CLR) required by this module
+# CLRVersion = ''
+
+# Processor architecture (None, X86, Amd64) required by this module
+# ProcessorArchitecture = ''
+
+# Modules that must be imported into the global environment prior to importing this module
+# RequiredModules = @()
+
+# Assemblies that must be loaded prior to importing this module
+# RequiredAssemblies = @()
+
+# Script files (.ps1) that are run in the caller's environment prior to importing this module.
+# ScriptsToProcess = @()
+
+# Type files (.ps1xml) to be loaded when importing this module
+# TypesToProcess = @()
+
+# Format files (.ps1xml) to be loaded when importing this module
+# FormatsToProcess = @()
+
+# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
+# NestedModules = @()
+
+# Functions to export from this module
+FunctionsToExport = @()
+
+# Cmdlets to export from this module
+CmdletsToExport = @()
+
+# Variables to export from this module
+VariablesToExport = @()
+
+# Aliases to export from this module
+AliasesToExport = @()
+
+# List of all modules packaged with this module.
+# ModuleList = @()
+
+# List of all files packaged with this module
+# FileList = @()
+
+# Private data to pass to the module specified in ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
+PrivateData = @{
+
+    PSData = @{
+
+        # Tags applied to this module. These help with module discovery in online galleries.
+        # Tags = @()
+
+        # A URL to the license for this module.
+        # LicenseUri = ''
+
+        # A URL to the main website for this project.
+        # ProjectUri = ''
+
+        # A URL to an icon representing this module.
+        # IconUri = ''
+
+        # ReleaseNotes of this module
+        # ReleaseNotes = ''
+
+        # The names of required or nested modules that are not packaged with this module.
+        # ExternalModuleDependencies = @()
+
+    } # End of PSData hashtable
+
+} # End of PrivateData hashtable
+
+# HelpInfo URI of this module
+# HelpInfoURI = ''
+
+# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
+# DefaultCommandPrefix = ''
+
+}
+```
+
 ## Specification
 
 The changes required for this RFC are relatively straightforward, and as follows:
 
-1. `New-ModuleManifest` would generate a template like what is shown above, omitting any details about the `PSData` section.
-1. Module import logic would read the manifest and pull the values for `Tags`, `LicenseUri`, `ProjectUri`, `IconUri` and `ReleaseNotes` from the top-level keys. If top-level keys were not defined with these values, it would look for values in a `PSData` section for backward compatibility.
+1. `New-ModuleManifest` would generate a template like what is shown above, omitting any details about the `PSData` section for the latest version, but including them for manifests with a downlevel version as the value of `-PowerShellVersion`.
+1. Module import logic would read the manifest and pull the values for `Tags`, `LicenseUri`, `ProjectUri`, `IconUri` and `ReleaseNotes` from the top-level keys in current plus future versions of PowerShell. If top-level keys were not defined with these values, it would look for values in a `PSData` section for backward compatibility (in cases where module versions are upgraded from older modules, we don't want users to be forced to change their manifest structure).
 1. If values are defined in both locations, an error would occur informing the module author that they need to remove one of the two keys.
 1. Add `-ExternalModuleDependencies` parameter to `New-ModuleManifest` (this is the only PowerShell Gallery value that is missing as a parameter).
+1. Update `New-ModuleManifest`'s `-PowerShellVersion` handling, such that it uses a default version of the latest version of PowerShell, with support for structuring a manifest properly for downlevel versions.
 1. Update `New-ModuleManifest` documentation (examples are missing PowerShell Gallery keys).
 1. Update `Test-ModuleManifest` to validate the keys in the new locations.
 1. Update `Update-ModuleManifest` to set the keys in the existing location if it is in use, or in the new location otherwise.
+1. Update `Import-Module` such that it allows import when a top-level key that it does not recognize is discovered. This is important and necessary to allow future versions of PowerShell to add keys to the top level while still allowing modules to be created for downlevel versions that also support the functionality identified by the new keys when loaded in a newer version.
 
 ## Alternate Proposals and Considerations
 
@@ -203,3 +333,15 @@ The changes required for this RFC are relatively straightforward, and as follows
 ### Keep `PSData` section in `New-ModuleManifest` output, but commented out with explanation
 
 @iSazonov proposed it may be clearer if the `PSData` section in `New-ModuleManifest` output, but commented out with a note indicating the keys have been moved to top level. I'm not convinced that would add clarity: it may confuse users as well. I think it would be better to identify the location change in the remarks section of the documentation for `New-ModuleManifest`, keeping `New-ModuleManifest` output clean, but I wanted to share the thought here for comment.
+
+### Isolate version-specific metadata and extension metadata into separate psd1 files
+
+If the `psd1` top-level key set is considered complete, when new keys are needed, where do they go? The current answer of placing new keys as subkeys under `PrivateData` in the `PSData` hashtable works, but it's just dealing with the problem by not dealing with the problem right now, and creating manifests that are more complicated than necessary. Instead, modules could have multiple `psd1` files, where files are created with a name in the format _moduleName_._extensionNameOrVersionNumber_.psd1. For example, we could have _moduleName_.PSGallery.psd1 as a manifest that stores PowerShell Gallery information. We could also have _moduleName_.7.psd1 as a manifest that stores new keys added to PowerShell 7.
+
+On the plus side, this strategy allows for new metadata to be defined in manifests today without breaking downlevel versions of PowerShell. This enables scenarios where modules can be defined for a minimum downlevel version of PowerShell while having functionality that lights up when those modules are loaded on a newer version.
+
+On the down side, it requires the management of additional files when working on manifests, which isn't necessarily simplifying manifest management.
+
+### General consideration to keep in mind
+
+While some people may find it difficult to justify these changes, at a minimum we need to have a clearly defined strategy for module manifest creation/consumption going forward that isn't held back by downlevel versions of PowerShell. In particular, we need to know where new keys should be stored, ideally in a way that makes sense to end users and is easy to manage. Please keep that in mind while considering the options presented here.
