Merge pull request #45 from ShaunLawrie/prerelease

v2

.github/workflows/build-test-publish.yml

@@ -70,6 +70,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           $ErrorActionPreference = "Stop"
+
           & ./PwshSpectreConsole/Build.ps1
           $env:PSModulePath = @($env:PSModulePath, ".\PwshSpectreConsole\") -join ":"
           Invoke-Pester -CI -ExcludeTag "ExcludeCI"
@@ -87,12 +88,24 @@ jobs:
           $latestPrereleaseTag = $latestPrereleaseVersion.Split("-prerelease")[1] # format is like -prerelease6, output here is just 6
           $latestPrereleaseVersion = [version]$latestPrereleaseVersion.Split("-prerelease")[0]
 
-          # Generate a new prerelease name, psgallery only allows characters 'a-zA-Z0-9' and a hyphen ('-') at the beginning of the prerelease string
-          $newPrereleaseTag = "prerelease" + (([int]$latestPrereleaseTag) + 1)
+          # Jump to package version if it's been bumped beyond the latest prerelease version
+          $currentVersion = [version]::new($version.Major, $version.Minor, $version.Build)
+          if ($latestPrereleaseVersion -lt $currentVersion) {
+            Write-Host "Latest prerelease version is less than the latest stable version, jumping to $currentVersion"
+            $newPrereleaseTag = "prerelease001"
+            $newVersion = $currentVersion
+          } elseif ($latestPrereleaseVersion -eq $currentVersion) {
+            Write-Host "Latest prerelease version is the same as the latest stable version, bumping prerelease tag"
+            $newPrereleaseTag = "prerelease" + (([int]$latestPrereleaseTag) + 1).ToString("000")
+            $newVersion = $currentVersion
+          } else {
+            # Generate a new prerelease name, psgallery only allows characters 'a-zA-Z0-9' and a hyphen ('-') at the beginning of the prerelease string
+            $newPrereleaseTag = "prerelease" + (([int]$latestPrereleaseTag) + 1).ToString("000")
 
-          # Prerelease will always be at least one minor version above the latest published stable version so when it's merged to main the minor version will get bumped
-          # To bump a major version the manifest would be edited manually to vnext.0.0 before merging to main
-          $newVersion = [version]::new($latestStableVersion.Major, $latestStableVersion.Minor + 1, 0)
+            # Prerelease will always be at least one minor version above the latest published stable version so when it's merged to main the minor version will get bumped
+            # To bump a major version the manifest would be edited manually to vnext.0.0 before merging to main
+            $newVersion = [version]::new($latestPrereleaseVersion.Major, $latestPrereleaseVersion.Minor + 1, 0)
+          }
 
           if($newVersion -eq $oldVersion) {
             Write-Host "Version is not being bumped in prerelease"

.github/workflows/unit-test-only.yml

@@ -1,31 +1,31 @@
-name: Run Unit Tests
-on:
-  push:
-
-permissions:
-  contents: write
-
-jobs:
-  unit-test:
-    name: Unit Test
-    runs-on: ubuntu-latest
-    if: github.repository_owner != 'ShaunLawrie' || (github.ref != 'refs/heads/main' && github.ref != 'refs/heads/prerelease')
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-      - name: Unit Test
-        shell: pwsh
-        run: |
-          $ErrorActionPreference = "Stop"
-          Write-Host "Working on ${{ github.ref }}"
-          & .\PwshSpectreConsole\Build.ps1
-          $env:PSModulePath = @($env:PSModulePath, ".\PwshSpectreConsole\") -join ":"
-          $PSVersionTable | Out-Host
-          Get-Module Pester -ListAvailable | Out-Host
-          Invoke-Pester -CI -ExcludeTag "ExcludeCI"
-      - name: Upload Snapshots
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: Snapshots
-          path: PwshSpectreConsole.Tests/@snapshots/*.txt
+name: Run Unit Tests
+on:
+  push:
+
+permissions:
+  contents: write
+
+jobs:
+  unit-test:
+    name: Unit Test
+    runs-on: ubuntu-latest
+    if: github.repository_owner != 'ShaunLawrie' || (github.ref != 'refs/heads/main' && github.ref != 'refs/heads/prerelease')
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: Unit Test
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          Write-Host "Working on ${{ github.ref }}"
+          & .\PwshSpectreConsole\Build.ps1
+          $env:PSModulePath = @($env:PSModulePath, ".\PwshSpectreConsole\") -join ":"
+          $PSVersionTable | Out-Host
+          Get-Module Pester -ListAvailable | Out-Host
+          Invoke-Pester -CI -ExcludeTag "ExcludeCI"
+      - name: Upload Snapshots
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: Snapshots
+          path: PwshSpectreConsole.Tests/@snapshots/*.txt

.gitignore

@@ -31,3 +31,4 @@ Working/
 # dotnet build files
 bin/
 obj/
+*.sln

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+👋🏻 Hi, and thank you for getting as far as reading the contributing guide!
+
+I'm thrilled that you're interested in contributing to this project. Your contributions are valuable and help make the module even better.
+
+## How to Contribute
+
+### 🐛 Reporting Bugs
+
+If you find a bug, please raise an issue on the GitHub repo. Please include as much detail as possible, including the version of the module you're using, the version of PowerShell, and the OS you're running on.
+
+### ✨ Suggesting Enhancements
+
+If you have an idea for an enhancement, please raise an issue on the GitHub repo as a starting point. This allows us to discuss a potential solution. I've found that discussing the enhancement before writing code can save a lot of time and effort.
+
+### 💻 Development Guidelines
+
+These are guidelines not rules, you can do whatever you want to make things work and open a PR but following these guidelines will make it easier for me to review your PR and get it merged.
+
+1. Fork this repo from the `prerelease` branch. This is where all development is done and pre-release versions are published from. The `main` branch is only used for production releases after the pre-release changes have had some more thorough testing.
+2. This is a PowerShell module and I intend on keeping it mostly PowerShell so those familiar with PowerShell but not C# can still contribute. If you're adding a feature that requires a C# class, please raise an issue first so we can discuss the best way to implement it. I'm aware not all features can be implemented in PowerShell and I'm open to adding C# code where necessary.
+3. Importing namespaces at the top of the `ps1` scripts is not advised, it makes the code more concise but it removes the ability to easily copy-paste code into a script.
+4. All public functions go in the `/PwshSpectreConsole/public` folder. These functions also need to be added to the FunctionsToExport array in the `PwshSpectreConsole.psd1` file to make them accessible to users.
+5. All internal functions go in the `/PwshSpectreConsole/private` folder.
+6. All functions in the `/PwshSpectreConsole/public` folder should have a comment-based help block at the top of the function. This is used to generate the markdown for the documentation site. See [`Read-SpectreMultiSelection.ps1`](PwshSpectreConsole/public/prompts/Read-SpectreMultiSelection.ps1) for an example. See [documentation help](/PwshSpectreConsole.Docs/README.md) for more information.
+7. All public functions should have unit tests in the `/PwshSpectreConsole.Tests` folder. These tests should be written in Pester and should test the function in a variety of scenarios. The tests should be named the same as the function they're testing with `.Tests` appended to the end. e.g. [`Read-SpectreMultiSelection.tests.ps1`](PwshSpectreConsole.Tests/prompts/Read-SpectreMultiSelection.tests.ps1).
+
+## Thanks to Those Who Have Already Contributed
+
+These people are awesome and you should go follow them to keep tabs on all the other awesome stuff they're doing:
+
+- **[@patriksvensson](https://github.com/patriksvensson)**  
+  The [Spectre Console](https://spectreconsole.net/) creator. Without the dotnet library this module wouldn't exist.
+- **[@dfinke](https://github.com/dfinke)**  
+  Doug Finke helped fix some broken table logic in the earliest days of the module yet his biggest contribution has been to my growth as a developer. Thanks for helping me gather the courage to build in the open.
+- **[@trackd](https://github.com/trackd)**  
+  The table whisperer. Most of the logic for translating between PowerShell objects and the format required by the Spectre Console table widgets has come from their big brain and it's melted mine. They're a crazy-talented PowerShell developer who has helped teach me a lot and their contributions are a big part of the v2 release.
+- **[@StartAutomating](https://github.com/StartAutomating)**  
+  Thanks for the sponsorship, EZOut and HelpOut modules. HelpOut is used to generate the markdown that powers the [pwshspectreconsole.com](https://pwshspectreconsole.com/reference/formatting/format-spectrebarchart/) documentation site.
+- **[@futuremotiondev](https://github.com/futuremotiondev)**, **[@ruckii](https://github.com/ruckii)** and **[@csillikd-messerli](https://github.com/csillikd-messerli)**  
+  Thank you for the issues raised and the fixes you've pulled together making this module better.
+
+## Contact Me
+
+If you have any questions, please reach out to me on Twitter [@shaun_lawrie](https://twitter.com/shaun_lawrie).  
+You can also find me on Discord in the [PowerShell discord](https://discord.gg/powershell) as `shaunlawrie`.

PwshSpectreConsole.Docs/README.md

@@ -0,0 +1,77 @@
+# Documentation
+
+Most documentation is generated from the comment-based help in the module functions. This means that the documentation is always up-to-date with the code. You don't need to format the comment based help correctly as any issues should be discovered when your PR is merged to the prerelease branch but if you need to make changes to the documentation locally you can follow the steps below.  
+
+## Testing the Documentation Locally
+
+This requires you have nodejs v20 installed. If you don't have nodejs installed, you can install it from [nodejs.org](https://nodejs.org/) or you can use my preferred method of using [nvm-windows](https://github.com/coreybutler/nvm-windows).
+
+1. Clone this repository and open a terminal in the root directory.
+2. Install the HelpOut PowerShell module by running `Install-Module helpout -Scope CurrentUser -RequiredVersion 0.5`. Version 0.5 is required because changes to the formatting in HelpOut can break the Markdown generation and 0.5 is what's being used in the Github Actions.
+3. Change to the docs directory `cd .\PwshSpectreConsole.Docs`.
+4. Run `npm install`.
+5. Run `npm run dev` to start the dev server. You should be able to view the documentation at [http://localhost:4321](http://localhost:4321)  
+6. To update the help for the public functions:
+   - Press `ctrl-c` in the terminal session that's hosting the docs dev server to stop it.
+   - Update the comment based help in your public functions. See [Comment Based Help](#comment-based-help) below for more information on how to format the help docs.
+   - Run `npm run update-docs:no-commit -- -TargetFunction Set-SpectreColors` again to see the changes for the function you've changed, replace "Set-SpectreColors" with the function you're working on. The dev server will start again after updating the docs and you can view the changes at [http://localhost:4321](http://localhost:4321).  
+7. When you're happy that the docs look correct you can open a PR with the changes. You don't have to commit the docs files, they will be autogenerated when your branch is merged into the prerelease branch of PwshSpectreConsole.
+
+> [!NOTE]  
+> If you're having troubles running the docs update because it can't delete files, it's likely that the files are locked by the PowerShell session in your editor session. Try closing your editor and running the update again.
+
+## Comment Based Help
+
+The comment based help in the module functions is used to generate the markdown for the documentation site. The comment based help is written in a specific format to ensure that the markdown is generated correctly.
+
+When generation the help the following fields are used and others are dropped:
+
+- `DESCRIPTION` is used as the main description on the docs site.
+- `PARAMETER` documentation will be kept and grouped under Parameters on the docs page.
+- `EXAMPLE` documentation is the hard part so two examples are provided below. You can provide multiple examples.
+
+> [!WARNING]  
+> You can't start your example with a comment line. There is a limitation in the way that the markdown is generated that means the first line of the example can't be a comment or it will break the markdown generation.
+
+### Example 1 - Basic Example
+
+For a standard function a simple example will only require the code required to make the function do its magic. In the example below the function Format-SpectreBarChart is used to create a bar chart but it requires data setup. The example code needs to work as one full statement that you could copy and paste into a PowerShell console so the data setup is part of the example.
+
+```powershell
+<#
+    .EXAMPLE
+    $data = @()
+
+    $data += New-SpectreChartItem -Label "Apples" -Value 10 -Color "Green"
+    $data += New-SpectreChartItem -Label "Oranges" -Value 5 -Color "DarkOrange"
+    $data += New-SpectreChartItem -Label "Bananas" -Value 2.2 -Color "#FFFF00"
+    
+    Format-SpectreBarChart -Data $data -Label "Fruit Sales" -Width 50
+#>
+```
+
+See the example in action at: [https://pwshspectreconsole.com/reference/formatting/format-spectrebarchart/](https://pwshspectreconsole.com/reference/formatting/format-spectrebarchart/)
+
+### Example 2 - Advanced Example
+
+For more complex functions you may not be able to generate an example without providing user input. If you were to try and generate an example for a function like was required for `Read-SpectreText` you would need to simulate a user typing.
+
+To generate user input you can add a `# Type` comment at the point in the example where the input is required. The example generator takes each double quoted string after the directive as a separate piece of user input, multiple inputs can be provided by separating them with a comma.
+
+e.g.
+
+1. `# Type "This is a test"` will type the string "This is a test" into the console with some delay between each character.  
+2. `# Type "This is a test", "↲"` will type the string "This is a test" and then press enter afterwards.
+3. `# Type "a"` will enter a single character "a" into the console.
+4. `# Type "↑", "↓", "↲", "<space>"` will press the up arrow key, down arrow key, enter, and space keys respectively.
+
+```powershell
+<#
+    .EXAMPLE
+    $favouriteColor = Read-SpectreText -Question "What's your favorite color?" -AnswerColor "Cyan1" -Choices "Black", "Green", "Magenta", "I'll never tell!"
+    # Type "orange", "↲", "magenta", "↲" to enter text that must match a choice in the choices list, orange will be rejected, magenta will be accepted
+    Write-SpectreHost "Your favourite color is '$favouriteColor'"
+#>
+```
+
+See the example in action at: [https://pwshspectreconsole.com/reference/prompts/read-spectretext/](https://pwshspectreconsole.com/reference/prompts/read-spectretext/)

PwshSpectreConsole.Docs/astro.config.mjs

@@ -1,51 +1,60 @@
-import { defineConfig } from "astro/config";
-import starlight from "@astrojs/starlight";
-
-import tailwind from "@astrojs/tailwind";
-
-// https://astro.build/config
-export default defineConfig({
-  integrations: [
-    starlight({
-      title: "PwshSpectreConsole",
-      editLink: {
-        baseUrl:
-          "https://github.com/ShaunLawrie/PwshSpectreConsole/edit/main/PwshSpectreConsole.Docs/",
-      },
-      favicon: "/favicon.png",
-      customCss: ["./src/tailwind.css"],
-      social: {
-        github: "https://github.com/ShaunLawrie/PwshSpectreConsole",
-        twitter: "https://twitter.com/Shaun_Lawrie",
-      },
-      sidebar: [
-        {
-          label: "Guides",
-          items: [
-            {
-              label: "Install",
-              link: "/guides/install/",
-            },
-            {
-              label: "Getting Started",
-              link: "/guides/get-started/",
-            },
-            {
-              label: "FAQs",
-              link: "/guides/faqs/",
-            },
-          ],
-        },
-        {
-          label: "Command Reference",
-          autogenerate: {
-            directory: "reference",
-          },
-        },
-      ],
-    }),
-    tailwind({
-      applyBaseStyles: false,
-    }),
-  ]
-});
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+
+import tailwind from "@astrojs/tailwind";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: "PwshSpectreConsole",
+      favicon: "/favicon.png",
+      customCss: ["./src/tailwind.css"],
+      social: {
+        rss: "https://shaunlawrie.com/rss.xml",
+        github: "https://github.com/ShaunLawrie/PwshSpectreConsole",
+        "x.com": "https://twitter.com/Shaun_Lawrie",
+        youtube: "https://www.youtube.com/@shaunlawrie",
+      },
+      components: {
+        Head: './src/components/Head.astro',
+      },
+      sidebar: [
+        {
+          label: "Guides",
+          items: [
+            {
+              label: "Install",
+              link: "/guides/install/",
+            },
+            {
+              label: "Getting Started",
+              link: "/guides/get-started/",
+            },
+            {
+              label: "Upgrading to v2",
+              link: "/guides/upgrading-to-v2/",
+              badge: {
+                text: "New",
+                variant: "tip",
+              },
+            },
+            {
+              label: "FAQs",
+              link: "/guides/faqs/",
+            },
+          ],
+        },
+        {
+          label: "Command Reference",
+          autogenerate: {
+            directory: "reference",
+          },
+        },
+      ],
+    }),
+    tailwind({
+      applyBaseStyles: false,
+    }),
+  ]
+});