Merge pull request #55 from theohbrothers/enhancement/entrypoint-util…

…ize-environment-variables-in-entrypoint-scripts Enhancement (entrypoint): Utilize environment variables in entrypoint scripts
theohbrothers · May 17, 2024 · ea4243d · ea4243d
2 parents 720926a + fb34755
commit ea4243d
Show file tree

Hide file tree

Showing 11 changed files with 116 additions and 221 deletions.
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -50,13 +50,13 @@
         {
             "label": "Invoke-Generate.ps1 (pwsh)",
             "type": "shell",
-            "command": "PROJECT_DIRECTORY=${input:PROJECT_DIRECTORY} RELEASE_TAG_REF=${input:RELEASE_TAG_REF} RELEASE_NOTES_VARIANT=${input:RELEASE_NOTES_VARIANT} RELEASE_NOTES_PATH=${input:RELEASE_NOTES_PATH} pwsh -Command 'src/scripts/ci/Invoke-Generate.ps1 -ProjectDirectory $env:PROJECT_DIRECTORY -ReleaseTagRef $env:RELEASE_TAG_REF -ReleaseNotesVariant $env:RELEASE_NOTES_VARIANT -ReleaseNotesPath $env:RELEASE_NOTES_PATH'",
+            "command": "PROJECT_DIRECTORY=${input:PROJECT_DIRECTORY} RELEASE_TAG_REF=${input:RELEASE_TAG_REF} RELEASE_NOTES_VARIANT=${input:RELEASE_NOTES_VARIANT} RELEASE_NOTES_PATH=${input:RELEASE_NOTES_PATH} pwsh -c 'src/scripts/ci/Invoke-Generate.ps1'",
             "group": "build"
         },
         {
             "label": "Invoke-Generate.ps1 (powershell)",
             "type": "shell",
-            "command": "PROJECT_DIRECTORY=${input:PROJECT_DIRECTORY} RELEASE_TAG_REF=${input:RELEASE_TAG_REF} RELEASE_NOTES_VARIANT=${input:RELEASE_NOTES_VARIANT} RELEASE_NOTES_PATH=${input:RELEASE_NOTES_PATH} powershell -Command 'src/scripts/ci/Invoke-Generate.ps1 -ProjectDirectory $env:PROJECT_DIRECTORY -ReleaseTagRef $env:RELEASE_TAG_REF -ReleaseNotesVariant $env:RELEASE_NOTES_VARIANT -ReleaseNotesPath $env:RELEASE_NOTES_PATH'",
+            "command": "PROJECT_DIRECTORY=${input:PROJECT_DIRECTORY} RELEASE_TAG_REF=${input:RELEASE_TAG_REF} RELEASE_NOTES_VARIANT=${input:RELEASE_NOTES_VARIANT} RELEASE_NOTES_PATH=${input:RELEASE_NOTES_PATH} powershell -c 'src/scripts/ci/Invoke-Generate.ps1'",
             "group": "build"
         }
     ]

diff --git a/README.md b/README.md
@@ -121,62 +121,55 @@ To create releases, reference the appropriate `release.yml` entrypoint CI templa
 
 Releases supports all tag refs. Tags *need not* follow [Semantic Versioning](https://semver.org/) though the convention is recommended.
 
-#### via Entrypoint scripts
+#### via Entrypoint script(s)
 
-##### Parameters
+##### Environment variables
 
-```powershell
-# Entrypoint scripts
-Invoke-Generate.ps1 [[-ProjectDirectory] <string>] [-ReleaseTagRef] <string> [[-ReleaseNotesVariant] <string>] [[-ReleaseNotesPath] <string>] [<CommonParameters>]
-Invoke-Release.ps1 -Namespace <string> -Repository <string> -ApiKey <string> [-ProjectDirectory <string>] [-TagName <string>] [-Name <string>] [-ReleaseNotesPath <string>] [-Draft <bool>] [-Prerelease <bool>] [-Asset <string>] [<CommonParameters>]
-Invoke-Release.ps1 -Namespace <string> -Repository <string> -ApiKey <string> [-ProjectDirectory <string>] [-TagName <string>] [-Name <string>] [-ReleaseNotesContent <string>] [-Draft <bool>] [-Prerelease <bool>] [-Asset <string>] [<CommonParameters>]
-```
+###### Generate and Release
+
+| Name | Value | Mandatory | Type |
+|:-:|:-:|:-:|:-:|
+| `PROJECT_DIRECTORY` | `/path/to/repository` | true | string |
+| `RELEASE_TAG_REF` | `vx.x.x` | true | string |
+
+###### Generate
+
+| Name | Value | Mandatory | Type |
+|:-:|:-:|:-:|:-:|
+| `RELEASE_NOTES_VARIANT` | `VersionDate-HashSubject-NoMerges` | false | string |
+| `RELEASE_NOTES_PATH` | `/path/to/repository/.release-notes.md` (full)<br>`.release-notes.md` (relative) | false | string |
+
+###### Release
+
+| Name | <center>Value</center> | Mandatory | Type |
+|:-:|:-|:-:|:-:|
+| `RELEASE_NAMESPACE` | <center>`mygithubnamespace`</center> | true | string |
+| `RELEASE_REPOSITORY` | <center>`my-project`</center> | true | string |
+| `GITHUB_API_TOKEN` | <center>`xxx`</center> | true | string |
+| `RELEASE_NAME` | <center>`My release name`</center> | false | string |
+| `RELEASE_NOTES_CONTENT` | <pre><code>My<br>multi-line<br>release<br>notes</code></pre> | false | string |
+| `RELEASE_DRAFT` | <center>`true` / `false`</center> | false | string |
+| `RELEASE_PRERELEASE` | <center>`true` / `false`</center> | false | string |
+| `RELEASE_ASSETS` | <pre><code>path/to/asset1.tar.gz<br>path/to/asset2.gz<br>path/to/asset3.zip<br>path/to/assets/*.gz<br>path/to/assets/*.zip</code></pre> | false | string |
 
 ##### Commands
 
-Simply define necessary environment variables and/or parameter values prior to executing the provided entrypoint script(s) within your CI environment to perform their respective functions.
+Simply populate applicable environment variables values prior to executing provided entrypoint script(s) within the CI environment to perform their respective functions.
 
-```powershell
-# CI global variables
-$env:GITHUB_API_TOKEN = 'xxx' # required for Release
-$env:RELEASE_TAG_REF = 'vx.x.x' # required for Generate and Release
+```shell
+# Clone project
+git clone https://github.com/theohbrothers/PSRepositoryReleaseManager.git --recurse-submodules ../PSRepositoryReleaseManager
 
-# Generate and Release variables
-#$env:PROJECT_DIRECTORY = "$(git rev-parse --show-toplevel)" # optional
-#$env:RELEASE_NOTES_PATH = "$(git rev-parse --show-toplevel)/.release-notes.md" # optional
+# Process applicable environment variables (e.g.)
+export PROJECT_DIRECTORY=$(git rev-parse --show-toplevel)
+export RELEASE_NAMESPACE="$GITHUB_REPOSITORY_OWNER"
+export RELEASE_REPOSITORY=$(basename "$(git rev-parse --show-toplevel)")
 
 # Generate (Generates release notes)
-#$env:RELEASE_NOTES_VARIANT='VersionDate-HashSubject-NoMerges' # optional
-$private:generateArgs = @{
-    ReleaseTagRef = $env:RELEASE_TAG_REF
-}
-if ($env:PROJECT_DIRECTORY) { $private:generateArgs['ProjectDirectory'] = $env:PROJECT_DIRECTORY }
-if ($env:RELEASE_NOTES_VARIANT) { $private:generateArgs['ReleaseNotesVariant'] = $env:RELEASE_NOTES_VARIANT }
-if ($env:RELEASE_NOTES_PATH) { $private:generateArgs['ReleaseNotesPath'] = $env:RELEASE_NOTES_PATH }
-./path/to/PSRepositoryReleaseManager/src/scripts/ci/Invoke-Generate.ps1 @private:generateArgs
+pwsh -c './../PSRepositoryReleaseManager/src/scripts/ci/Invoke-Generate.ps1'
 
 # Release (Creates GitHub release)
-$env:RELEASE_NAMESPACE = 'mygithubnamespace' # required
-$env:RELEASE_REPOSITORY = 'my-project' # required
-#$env:RELEASE_NAME = 'My release name' # optional
-#$env:RELEASE_NOTES_CONTENT = Get-Content $env:RELEASE_NOTES_PATH -Raw # optional
-#$env:RELEASE_DRAFT = 'false' # optional
-#$env:RELEASE_PRERELEASE = 'false' # optional
-#$env:RELEASE_ASSETS = @('path/to/asset1.tar.gz', 'path/to/asset2.gz', 'path/to/asset3.zip', 'path/to/assets/*.gz', 'path/to/assets/*.zip') # optional
-$private:releaseArgs = @{
-    Namespace = $env:RELEASE_NAMESPACE
-    Repository = $env:RELEASE_REPOSITORY
-    ApiKey = $env:GITHUB_API_TOKEN
-}
-if ($env:PROJECT_DIRECTORY) { $private:generateArgs['ProjectDirectory'] = $env:PROJECT_DIRECTORY }
-if ($env:RELEASE_TAG_REF) { $private:releaseArgs['TagName'] = $env:RELEASE_TAG_REF }
-if ($env:RELEASE_NAME) { $private:releaseArgs['Name'] = $env:RELEASE_NAME }
-if ($env:RELEASE_NOTES_PATH) { $private:releaseArgs['ReleaseNotesPath'] = $env:RELEASE_NOTES_PATH }
-elseif ($env:RELEASE_NOTES_CONTENT) { $private:releaseArgs['ReleaseNotesContent'] = $env:RELEASE_NOTES_CONTENT }
-if ($env:RELEASE_DRAFT) { $private:releaseArgs['Draft'] = [System.Convert]::ToBoolean($env:RELEASE_DRAFT) }
-if ($env:RELEASE_PRERELEASE) { $private:releaseArgs['Prerelease'] = [System.Convert]::ToBoolean($env:RELEASE_PRERELEASE) }
-if ($env:RELEASE_ASSETS) { $private:releaseArgs['Asset'] = $env:RELEASE_ASSETS }
-./path/to/PSRepositoryReleaseManager/src/scripts/ci/Invoke-Release.ps1 @private:releaseArgs
+pwsh -c './../PSRepositoryReleaseManager/src/scripts/ci/Invoke-Release.ps1'
 ```
 
 ## Maintenance

diff --git a/src/PSRepositoryReleaseManager/PSRepositoryReleaseManager.Tests.ps1 b/src/PSRepositoryReleaseManager/PSRepositoryReleaseManager.Tests.ps1
@@ -2,45 +2,41 @@ Describe "PSRepositoryReleaseManager" -Tag 'Integration' {
     BeforeAll {
         $ErrorView = 'NormalView'
         $env:RELEASE_TAG_REF = git describe --tags --abbrev=0
+        $env:PROJECT_DIRECTORY = "$(git rev-parse --show-toplevel)"
     }
     BeforeEach {
     }
     AfterEach {
+        $env:RELEASE_NOTES_VARIANT = $null
+        $env:RELEASE_NOTES_PATH = $null
     }
-    It "Runs Invoke-Generate.ps1 -ReleaseTagRef" {
-        $stdout = ../src/scripts/ci/Invoke-Generate.ps1 -ReleaseTagRef $env:RELEASE_TAG_REF
+    It "Runs Invoke-Generate.ps1 with `$env:PROJECT_DIRECTORY `$env:RELEASE_TAG_REF" {
+        $stdout = ../src/scripts/ci/Invoke-Generate.ps1
         "Generate notes content:" | Write-Verbose
         Get-Content -Path "$stdout" | Out-String -Stream | % { $_.Trim() } | ? { $_ } | Write-Host
     }
-    It "Runs Invoke-Generate.ps1 -ProjectDirectory -ReleaseTagRef" {
-        $private:ProjectDir = "$(git rev-parse --show-toplevel)"
-
-        $stdout = ../src/scripts/ci/Invoke-Generate.ps1 -ProjectDirectory $private:ProjectDir -ReleaseTagRef $env:RELEASE_TAG_REF
-        "Generate notes content:" | Write-Verbose
-        Get-Content -Path "$stdout" | Out-String -Stream | % { $_.Trim() } | ? { $_ } | Write-Host
-    }
-    It "Runs Invoke-Generate.ps1 -ReleaseTagRef -ReleaseNotesVariant" {
+    It "Runs Invoke-Generate.ps1 with `$env:PROJECT_DIRECTORY `$env:RELEASE_TAG_REF `$env:RELEASE_NOTES_VARIANT" {
         $env:RELEASE_NOTES_VARIANT = 'Changes-HashSubject-NoMerges'
 
-        $stdout = ../src/scripts/ci/Invoke-Generate.ps1 -ReleaseTagRef $env:RELEASE_TAG_REF -ReleaseNotesVariant $env:RELEASE_NOTES_VARIANT
+        $stdout = ../src/scripts/ci/Invoke-Generate.ps1
         "Generate notes content:" | Write-Verbose
         Get-Content -Path "$stdout" | Out-String -Stream | % { $_.Trim() } | ? { $_ } | Write-Host
     }
-    It "Runs Invoke-Generate.ps1 -ReleaseTagRef -ReleaseNotesPath (full)" {
+    It "Runs Invoke-Generate.ps1 with `$env:PROJECT_DIRECTORY `$env:RELEASE_TAG_REF `$env:RELEASE_NOTES_PATH (full)" {
         $env:RELEASE_NOTES_PATH = "$(git rev-parse --show-toplevel)/.release-notes.fullpath.md"
 
-        $stdout = ../src/scripts/ci/Invoke-Generate.ps1 -ReleaseTagRef $env:RELEASE_TAG_REF -ReleaseNotesPath $env:RELEASE_NOTES_PATH
+        $stdout = ../src/scripts/ci/Invoke-Generate.ps1
         "Generate notes content:" | Write-Verbose
         Get-Content -Path "$stdout" | Out-String -Stream | % { $_.Trim() } | ? { $_ } | Write-Host
     }
-    It "Runs Invoke-Generate.ps1 -ReleaseTagRef -ReleaseNotesPath (relative)" {
+    It "Runs Invoke-Generate.ps1 with `$env:PROJECT_DIRECTORY `$env:RELEASE_TAG_REF `$env:RELEASE_NOTES_PATH (relative)" {
         $env:RELEASE_NOTES_PATH = ".release-notes.relativepath.md"
 
-        $stdout = ../src/scripts/ci/Invoke-Generate.ps1 -ReleaseTagRef $env:RELEASE_TAG_REF -ReleaseNotesPath $env:RELEASE_NOTES_PATH
+        $stdout = ../src/scripts/ci/Invoke-Generate.ps1
         "Generate notes content:" | Write-Verbose
         Get-Content -Path "$stdout" | Out-String -Stream | % { $_.Trim() } | ? { $_ } | Write-Host
     }
-    It "Runs Invoke-Generate.ps1 -ReleaseTagRef -ReleaseNotesVariant -ReleaseNotesPath (all variants)" {
+    It "Runs Invoke-Generate.ps1 with `$env:PROJECT_DIRECTORY `$env:RELEASE_TAG_REF `$env:RELEASE_NOTES_VARIANT `$env:RELEASE_NOTES_PATH (all variants)" {
         $ReleaseNotesVariant = Get-ChildItem "../src/PSRepositoryReleaseManager/generate/variants" | % { $_.BaseName }
         "Release notes variants:" | Write-Verbose
         $ReleaseNotesVariant | Write-Host
@@ -49,7 +45,7 @@ Describe "PSRepositoryReleaseManager" -Tag 'Integration' {
             $env:RELEASE_NOTES_VARIANT = $variant
             $env:RELEASE_NOTES_PATH = "$(git rev-parse --show-toplevel)/.release-notes.$variant.md"
 
-            $stdout = ../src/scripts/ci/Invoke-Generate.ps1 -ReleaseTagRef $env:RELEASE_TAG_REF -ReleaseNotesVariant $env:RELEASE_NOTES_VARIANT -ReleaseNotesPath $env:RELEASE_NOTES_PATH
+            $stdout = ../src/scripts/ci/Invoke-Generate.ps1
             "Generate notes content:" | Write-Verbose
             Get-Content -Path "$stdout" | Out-String -Stream | % { $_.Trim() } | ? { $_ } | Write-Host
         }

diff --git a/src/scripts/ci/Invoke-Generate.ps1 b/src/scripts/ci/Invoke-Generate.ps1
@@ -1,40 +1,38 @@
 [CmdletBinding()]
-param(
-    [Parameter(Mandatory=$false)]
-    [ValidateScript({Test-Path -Path $_ -PathType Container})]
-    [string]$ProjectDirectory
-    ,
-    [Parameter(Mandatory=$true)]
-    [ValidateNotNullOrEmpty()]
-    [string]$ReleaseTagRef
-    ,
-    [Parameter(Mandatory=$false)]
-    [ValidateNotNullOrEmpty()]
-    [string]$ReleaseNotesVariant
-    ,
-    [Parameter(Mandatory=$false)]
-    [ValidateNotNullOrEmpty()]
-    [string]$ReleaseNotesPath
+param()
 
-    <# Examples
+<# Examples
 
-    # Maximum defaults
-    ./Invoke-Generate.ps1 -ReleaseTagRef v1.0.12
+# Maximum defaults
+$env:RELEASE_TAG_REF = 'v1.0.12'
+./Invoke-Generate.ps1
 
-    # Default -ReleaseNotesVariant and -ReleaseNotesPath
-    ./Invoke-Generate.ps1 -ProjectDirectory '/path/to/repository' -ReleaseTagRef v1.0.12
+# Default release notes variant and release notes path
+$env:PROJECT_DIRECTORY = '/path/to/repository'
+$env:RELEASE_TAG_REF = 'v1.0.12'
+./Invoke-Generate.ps1
 
-    # Default -ReleaseNotesPath
-    ./Invoke-Generate.ps1 -ProjectDirectory '/path/to/repository' -ReleaseTagRef v1.0.12 -ReleaseNotesVariant 'Changes-HashSubject-NoMerges'
+# Default release notes path
+$env:PROJECT_DIRECTORY = '/path/to/repository'
+$env:RELEASE_TAG_REF = 'v1.0.12'
+$env:RELEASE_NOTES_VARIANT = 'Changes-HashSubject-NoMerges'
+./Invoke-Generate.ps1
 
-    # Custom -ReleaseNotesPath relative to -ProjectDirectory
-    ./Invoke-Generate.ps1 -ProjectDirectory '/path/to/repository' -ReleaseTagRef v1.0.12 -ReleaseNotesVariant 'Changes-HashSubject-NoMerges' -ReleaseNotesPath 'my-custom-release-notes.md'
+# Custom -ReleaseNotesPath relative to -ProjectDirectory
+$env:PROJECT_DIRECTORY = '/path/to/repository'
+$env:RELEASE_TAG_REF = 'v1.0.12'
+$env:RELEASE_NOTES_VARIANT = 'Changes-HashSubject-NoMerges'
+$env:RELEASE_NOTES_PATH = 'my-custom-release-notes.md'
+./Invoke-Generate.ps1
 
-    # No defaults
-    ./Invoke-Generate.ps1 -ProjectDirectory '/path/to/repository' -ReleaseTagRef v1.0.12 -ReleaseNotesVariant 'Changes-HashSubject-NoMerges' -ReleaseNotesPath '/path/to/repository/.release-notes.md'
-    #>
+# No defaults
+$env:PROJECT_DIRECTORY = '/path/to/repository'
+$env:RELEASE_TAG_REF = 'v1.0.12'
+$env:RELEASE_NOTES_VARIANT = 'Changes-HashSubject-NoMerges'
+$env:RELEASE_NOTES_PATH = '/path/to/repository/.release-notes.md'
+./Invoke-Generate.ps1
 
-)
+#>
 
 $ErrorActionPreference = 'Stop'
 $ErrorView = 'NormalView'
@@ -46,26 +44,25 @@ try {
     Import-Module "$(git rev-parse --show-toplevel)\src\PSRepositoryReleaseManager\PSRepositoryReleaseManager.psm1" -Force -Verbose
 
     # Generate release notes
-    if ($private:ProjectDirectory) {
-        $private:ProjectDir = $private:ProjectDirectory
+    if ($env:PROJECT_DIRECTORY) {
+        $private:ProjectDir = $env:PROJECT_DIRECTORY
     }else {
         $private:superProjectDir = git rev-parse --show-superproject-working-tree
         if ($private:superProjectDir) {
             $private:ProjectDir = $private:superProjectDir
             "Using superproject path '$private:ProjectDir'" | Write-Verbose
         }else {
-            $private:ProjectDir = git rev-parse --show-toplevel
-            "Superproject does not exist. Using project path '$private:ProjectDir'" | Write-Verbose
+            throw "`$env:PROJECT_DIRECTORY is undefined or superproject directory cannot be determined." | Write-Verbose
         }
     }
     $private:generateArgs = @{
         Path = $private:ProjectDir
-        TagName = $private:ReleaseTagRef
-        Variant = if ($private:ReleaseNotesVariant) { $private:ReleaseNotesVariant } else { 'VersionDate-HashSubject-NoMerges' }
-        ReleaseNotesPath = if ($private:ReleaseNotesPath) {
-                               "Using specified release notes path '$private:ReleaseNotesPath'" | Write-Verbose
-                               if ([System.IO.Path]::IsPathRooted($private:ReleaseNotesPath)) { $private:ReleaseNotesPath }
-                               else { "$private:ProjectDir/$private:ReleaseNotesPath" }
+        TagName = $env:RELEASE_TAG_REF
+        Variant = if ($env:RELEASE_NOTES_VARIANT) { $env:RELEASE_NOTES_VARIANT } else { 'VersionDate-HashSubject-NoMerges' }
+        ReleaseNotesPath = if ($env:RELEASE_NOTES_PATH) {
+                               "Using specified release notes path '$env:RELEASE_NOTES_PATH'" | Write-Verbose
+                               if ([System.IO.Path]::IsPathRooted($env:RELEASE_NOTES_PATH)) { $env:RELEASE_NOTES_PATH }
+                               else { "$private:ProjectDir/$env:RELEASE_NOTES_PATH" }
                            }else {
                                $private:defaultReleaseNotesPath = "$(git rev-parse --show-toplevel)/.release-notes.md"
                                "Using the default release notes path '$private:defaultReleaseNotesPath'" | Write-Verbose