@halospv3/hce.shared-config 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [2.1.0](https://github.com/halospv3/hce.shared/compare/v2.0.1...v2.1.0) (2024-03-18)
+
+
+### Features
+
+* add plugin '@semantic-release/exec' ([61447fc](https://github.com/halospv3/hce.shared/commit/61447fcdef19db8cd7f103edd54354fa5c4cb202))
+
+## [2.0.1](https://github.com/halospv3/hce.shared/compare/v2.0.0...v2.0.1) (2024-03-18)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @semantic-release/commit-analyzer to v12 ([87c6d12](https://github.com/halospv3/hce.shared/commit/87c6d12c3ab5243e50a0c1b0cf3dafd6c4c20ffa))
+* **dotnet:** try making the '$(RepoRoot)/publish' directory before zipping ([0241146](https://github.com/halospv3/hce.shared/commit/024114698c89f557513a61400729a609d7637bf0))
+
 ## [2.0.0](https://github.com/halospv3/hce.shared/compare/v1.2.7...v2.0.0) (2024-03-17)
 
 

package/README.md

@@ -3,74 +3,72 @@ Infrastructure resources shared with other HaloSPV3 repositories.
 
 It is recommended to "install" this repo via [Node Package Manager](#npm)
 
-## NPM
+## Usage
 
-### Usage
 
-`npm install --save-dev HaloSPV3/HCE.Shared`
+### 1. Install `@halospv3/hce.shared-config`
 
-See [package.json](package.json), [src/index.ts](src/index.ts), and [static/.releaserc.yml](static/.releaserc.yml)
+This project is packaged and published via NPM. As such...
+```sh
+npm install --save-dev @halospv3/hce.shared-config
+```
 
-#### Set Up CommitLint
+### 2. Customize Semantic Release
+
+WARNING! Defining a property will *overwrite* the previous value. Arrays and objects are *not* merged. You can...
+- Assign to top-level variables to avoid modifying the plugins array.
+- Write your config in CJS and manually merge objects and arrays.
+
+**Configs**
+- `hce.shared-config`: [static/.releaserc.yml](static/.releaserc.yml)
+- [dotnet/.releaserc.cjs](dotnet/.releaserc.cjs) based on [BinToss/GroupBox.Avalonia's Semantic Release config](https://github.com/BinToss/GroupBox.Avalonia).
+
+**Notable Plugin Properties**
+- [`@semantic-release/commit-analyzer`](https://github.com/semantic-release/commit-analyzer#options)
+  - preset (set to conventionalcommits)
+  - parserOpts
+  - releaseRules
+- [`@semantic-release/release-notes-generator`](https://github.com/semantic-release/release-notes-generator#options)
+  - preset (set to conventionalcommits)
+  - parserOpts
+  - writerOpts
+- [`@semantic-release/changelog`](https://github.com/semantic-release/changelog#options)
+  - changelogFile (default: CHANGELOG.md)
+- [`@semantic-release/git`](https://github.com/semantic-release/git#options)
+  - assets (default: ['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'])
+- `@semantic-release/exec`
+  - prepareCmd
+- [`@semantic-release/github`](https://github.com/semantic-release/github#options)
+  - assets
+  - draftRelease (default: false)
+
+### 3. Set Up CommitLint
 
 ```json
 // package.json
+// body-max-line-length is now a Warning instead of an Error.
 {
   "commitlint": {
     "extends": [
-      "@commitlint/config-conventional"
-    ]
+        "@commitlint/config-conventional"
+    ],
+    "rules": {
+      "body-max-line-length": [
+        1,
+        "always",
+        100
+      ]
+    }
   }
 }
 ```
 
-```bash
-npx husky install
+```sh
+npx husky
 npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'
 ```
 
-### Help
-
-#### Need your VersionInfo before the actual release?
-
-Make sure you are synced up before doing a dry-run! Semantic-release will fail before printing the version if you aren't synced with the remote!
-Yes, I know that's ridiculous.
-Run `npx semantic-release --dry-run --plugins "@semantic-release/commit-analyzer,semantic-release-export-data"`
-If the first plugin doesn't run into any issues and infers a version bump from unreleased commits, it will print the next version to the console.
-The [second plugin](https://github.com/felipecrs/semantic-release-export-data#readme) will export the next version and other information as GitHub Action Step exports.
-
-#### Don't want to publish a Node package? 
-
-Add the following to your `package.json`:
-```json
-{
-    "private": true,
-}
-```
-
-## .NET
-
-See [dotnet/](dotnet/)
-
-GitHub Actions workflow examples are in [dotnet/.github/workflows/](dotnet/.github/workflows/).
-
-#### TODO:
-
-Eventually, I hope to make boilerplate workflows useable from via relative paths e.g.
-```yml
-jobs:
-    release:
-        steps:
-        - uses: actions/checkout@v3
-        - name: dotnet build/publish; copy release artifacts to './publish/'
-          uses: ./node_modules/@halospv3/hce.shared/dotnet/.github/workflows/dotnet-release.yml
-            with:
-                projects:
-                    - src/lib/lib.csproj
-                    - src/lib-sample/sample.csproj
-```
-
-### Directory.Build.props
+### 4. (dotnet) Add/Edit Directory.Build.props
 
 Add the file `Directory.Build.props` to your repository's root directory or solution directory if you haven't already.
 Then, add the following properties:
@@ -78,7 +76,7 @@ Then, add the following properties:
 <Project>
     <PropertyGroup>
         <ProjectRootDir>$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), '.git/index'))</ProjectRootDir>
-        <HCESharedDir>$(ProjectRootDir)/node_modules/@halospv3/hce.shared/</HCESharedDir>
+        <HCESharedDir>$(ProjectRootDir)/node_modules/@halospv3/hce.shared-config/</HCESharedDir>
     </PropertyGroup>
 </Project>
 ```
@@ -87,10 +85,12 @@ These may evaluate to the following:
 | Property | Evaluated Value|
 | - | - |
 |`ProjectRootDir` | `c:\Repos\HaloSPV3\HCE.Shared\` |
-|`HCESharedDir`| `c:\Repos\HaloSPV3\HCE.Shared\node_modules\@halospv3\hce.shared\` |
+|`HCESharedDir`| `c:\Repos\HaloSPV3\HCE.Shared\node_modules\@halospv3\hce.shared-config\` |
 
 <br/>
 
+#### CI/CD-Only Properties
+
 If you want properties set only in a CI/CD environment (e.g. a GitHub workflow), add the following conditional property group to the props file:
 ```xml, diff
 <Project>
@@ -101,16 +101,81 @@ If you want properties set only in a CI/CD environment (e.g. a GitHub workflow),
     <PropertyGroup Condition=" '$(CI)' == 'true' ">
         <Configuration>Release</Configuration>
         <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+        <Deterministic>true</Deterministic>
    </PropertyGroup>
 </Project>
 ```
 > Any properties added to this conditional property group will only be evaluated when `$(CI)` is defined either as a property or as an environment variable. This is most useful for properties such as `ContinuousIntegrationBuild`.
 
-### GitVersion
+#### GitVersion
 
 By default, GitVersion will search only the "current directory" for `GitVersion.yml`. GitVersion has a lesser-known CLI argument, "Path" which allows users to specify the path to `GitVersion.yml`. The NuGet package `GitVersion.MSBuild` exposes this as the read-write property `$(GitVersion_Path)`.
+
+If you're satisfied by [dotnet/GitVersion.yml](dotnet/GitVersion.yml), you can configure GitVersion to use this config file. GitVersion does not have 'extend' functionality typical of Node.js packages.
 ```xml
 <PropertyGroup>
-    <GitVersion_Path>../SiblingDir/GitVersion.yml</GitVersion_Path>
+    <GitVersion_Path>$(ProjectRootDir)/node_modules/@halospv3/hce.shared-config/dotnet/GitVersion.yml</GitVersion_Path>
 </PropertyGroup>
+```
+
+## Tips
+
+### Need your VersionInfo before the actual release?
+
+If you want to use this information in other Semantic Release steps, you'll need `semantic-release-export-data`.
+```sh
+npm i -D semantic-release-export-data
+```
+
+Run the following to preview the version:
+```sh
+npx semantic-release --dry-run --plugins "@semantic-release/commit-analyzer,semantic-release-export-data"
+```
+If the first plugin doesn't run into any issues and infers a version bump from unreleased commits, it will print the next version to the console.
+The [second plugin](https://github.com/felipecrs/semantic-release-export-data#readme) will export the next version and other information as GitHub Action Step exports.
+
+### Don't intend to publish a Node package? 
+
+Add the following to `package.json`:
+```json
+{
+    "private": true,
+}
+```
+
+## TODO:
+
+### Reusable, configurable GitHub workflows
+
+```yml
+jobs:
+  release:
+    steps:
+    - uses: actions/checkout@v3
+    - name: dotnet build/publish; copy release artifacts to './publish/'
+      uses: ./node_modules/@halospv3/hce.shared/dotnet/.github/workflows/dotnet-release.yml
+        with:
+          projects:
+            - src/lib/lib.csproj
+            - src/lib-sample/sample.csproj
+```
+
+### Ease Semantic Release Configuration
+
+JSON/YAML configs *could* have merge-edit capabilities driven by data from custom, top-level properties. Each property would contain the command moniker and the config data (parameters) similar to RPC implementations.
+This will require quite a bit of datatype validation behind the scenes.
+```json
+{
+  "modify_plugins": {
+    "op": "Append",
+    "data": [
+      [
+        "newplugin",
+        {
+          "newpluginoption": true
+        }
+      ]
+    ]
+  }
+}
 ```

package/dotnet/.github/workflows/_unit_test.yml

@@ -0,0 +1,34 @@
+# inspired by https://github.com/GitTools/GitVersion/blob/main/.github/workflows/_unit_tests.yml
+on:
+  workflow_call:
+env:
+  DOTNET_ROLL_FORWARD: "Major"
+
+jobs:
+  unit_test:
+    name: Unit Tests (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          cache: "npm"
+          check-latest: true
+          node-version-file: package.json
+      - run: npm i -g npm@latest
+
+      - run: npm ci
+
+      - uses: actions/setup-dotnet@v4.0.0
+        with:
+          dotnet-version: "8.x"
+
+      - run: dotnet test

package/dotnet/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+# Inspired by https://github.com/GitTools/GitVersion/blob/main/.github/workflows/ci.yml
+
+name: CI
+
+on:
+  push:
+    branches-ignore: # if CI must run on these branches, Release will call CI
+      - main
+      - develop
+  pull_request:
+  workflow_call:
+
+env:
+  DOTNET_ROLL_FORWARD: "Major"
+  DOTNET_CLI_TELEMETRY_OPTOUT: 1
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+  DOTNET_NOLOGO: 1
+
+jobs:
+  unit_test:
+    name: Unit Test
+    uses: ./.github/workflows/_unit_test.yml

package/dotnet/.github/workflows/dotnet-release.yml

@@ -1,9 +1,8 @@
+# Test changes locally with https://github.com/nektos/act
 name: dotnet-release
 
 # TODO
-# - Get AssemblyName, RuntimeIdentifier (RID) from Directory.Build.props, *.csproj
 # - Allow workflows to be driven by the project(s)
-# - support multiple ASSEMBLYNAME parameters for matrices
 
 on:
   push:
@@ -13,60 +12,42 @@ on:
     - "**/*.md"
     - "**/*.txt"
 
-permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-
 jobs:
+  ci:
+    name: CI # run test.yml. If it fails, this job fails.
+    uses: ./.github/workflows/ci.yml
   release:
+    needs: [ci] # start 'release' if 'ci' completes successfully
     runs-on: ubuntu-latest
-    strategy: # TODO: Get variables from config file(s). May require a parent workflow to allow matrix runs.
-      matrix:
-        RID: [ "win-x86", "win-x64" ]
-        ASSEMBLYNAME: [ "SPV3.Loader", "SPV3.Installer", "HXE" ] #TODO: update
-    env:
-        PROJPATH: "./src/${{ matrix.ASSEMBLYNAME }}.csproj"
-
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
     steps:
-    - name: Wait for build to succeed
-      uses: lewagon/wait-on-check-action@v1.3.3
-      with:
-        ref: ${{ github.ref }}
-        check-name: 'Build (${{matrix.RID}}, ${{matrix.ASSEMBLYNAME}})'
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        wait-interval: 10
-
     ################
     # SETUP
     ################
     - uses: actions/checkout@v4
       with:
-        fetch-depth: 0 # Required by GitVersion
+        fetch-depth: 0 # Required by GitVersion, Semantic Release
         submodules: "recursive" # submodule fetch depth unknown
-    - uses: actions/setup-dotnet@v4
+    
+    - name: Setup Dotnet
+      uses: actions/setup-dotnet@v4
+    
     - name: Setup Node
       uses: actions/setup-node@v4
-    - run: npm ci # Required by Semantic Release
 
-    ################
-    # BUILD
-    ################
-    - name: dotnet publish
-      run: |
-        dotnet publish ${{ matrix.PROJPATH }} -c Release --no-self-contained -p:ContinuousIntegrationBuild=true
-        src/.msb.noConfig.ps1
+    - name: NPM - Update NPM to Latest
+      run: npm install -g npm@latest
 
-    # required variables: TargetFramework, RuntimeIdentifier, GitVersion_FullSemVer
-    # TODO: replace with ZipPublishDir (see Bintoss/GroupBox.Avalonia)
-    - name: Compress Publish Artifacts
-      shell: pwsh
-      run: |
-        $archiveName = "$env:ASSEMBLYNAME.$env:RID.$env:GitVersion_FullSemVer.zip";
-        Compress-Archive -Path publish -DestinationPath $archiveName -CompressionLevel Optimal;
+    - name: NPM - Clean Install
+      run: npm ci # Required by Semantic Release
 
     ################
     # RELEASE
+    # `dotnet publish` must be executed by @semantic-release/exec
+    # see 'dotnet/.releaserc.cjs'
     ################
     # https://github.com/semantic-release/semantic-release
     - name: Semantic Release
@@ -74,12 +55,6 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-    - name: Upload Artifact
-      uses: actions/upload-artifact@v4
-      with:
-        name: publish-artifacts
-        path: publish
-
     - name: Publish to GitHub Packages
       working-directory: publish
       run: dotnet nuget push *.nupkg -s https://nuget.pkg.github.com/HaloSPV3/index.json -k ${{ secrets.GITHUB_TOKEN }}

package/dotnet/.releaserc.cjs

@@ -0,0 +1,77 @@
+/** Semantic-Release configuration for GroupBox.Avalonia
+ * @extends { hceSharedConfig }
+ * 
+ * <-- TABLE OF CONTENTS -->
+ * - Insert-Edit Plugins
+ * - Append Plugins
+ */
+
+/**
+  * @typedef { object } PluginOptionsGit 
+  * @prop { string } message
+  * @prop {[ string | [string] | {path:string} ]} assets
+  */
+
+/**
+ * @type {import("semantic-release").Options}
+ */
+const hceSharedConfig = require('@halospv3/hce.shared-config')
+if (process.argv.includes("--debug") || process.argv.includes("--verbose")) {
+  console.info("hce.shared-config:\n" + JSON.stringify(hceSharedConfig, null, 2))
+}
+/** 
+ * @type { typeof hceSharedConfig.plugins }
+ */
+const newPlugins = hceSharedConfig.plugins;
+
+//#region Insert-Edit Plugins
+/* Insert and/or configure plugins. Can be used to load plugin A's Prepare step
+before plugin B's Prepare step. or edit a plugin's existing configuration */
+for (var i = 0; i < newPlugins.length; i++) {
+  /** e.g.
+  //#region Git Options | https://github.com/semantic-release/git#options
+  // if defined without plugin options, replace with tuple-like array with assets option defined.
+  if (plugins[i] === "@semantic-release/git") {
+    plugins[i] = [plugins[i], { assets: ["README.md", "CHANGELOG.md"] }]
+  }
+  if (plugins[i][0] === "@semantic-release/git") {
+    // if assets array undefined, define it
+    if (!plugins[i][1].assets) {
+      plugins[i][1].assets = [];
+    }
+    // ensure README.md is in assets array
+    if (!plugins[i][1].assets.some(a => a === "README.md" || a.path === "README.md")) {
+      plugins[i][1].assets.push("README.md");
+    }
+    // ensure CHANGELOG.md is in assets array
+    if (!plugins[i][1].assets.some(a => a === "CHANGELOG.md" || a.path === "CHANGELOG.md")) {
+      plugins[i][1].assets.push("CHANGELOG.md");
+    }
+  }
+  //#endregion Git Options
+  */
+}
+//#endregion Insert-Edit Plugins
+
+//#region Append Plugins
+newPlugins.push(
+  // APPEND this array of [pluginName, pluginConfig] to plugins
+  // https://github.com/semantic-release/exec#usage
+  ["@semantic-release/exec", {
+    // 'ZipPublishDir' zips each publish folder to ./publish/*.zip
+    prepareCmd: "dotnet publish ./GroupBox.Avalonia/GroupBox.Avalonia.csproj && dotnet publish ./GroupBox.Avalonia.Sample/GroupBox.Avalonia.Sample.csproj"
+  }]
+)
+//#endregion Append Plugins
+
+if (process.argv.includes("--debug") || process.argv.includes("--verbose")) {
+  console.info("modified plugins array:\n" + JSON.stringify(newPlugins, null, 2))
+}
+
+/**
+ * @type {import("semantic-release").Options}
+ */
+module.exports = {
+  extends: "@halospv3/hce.shared-config",
+  plugins: newPlugins
+};

package/dotnet/ZipPublishDir.targets

@@ -1,17 +1,23 @@
 <Project>
-  <!-- https://learn.microsoft.com/en-us/visualstudio/msbuild/zipdirectory-task?view=vs-2022 -->
+  <!-- todo: refactor to Task so users can configure input variables e.g. ZipPublishDir_AppendVariantArgs -->
   <Target Name="ZipPublishDir" AfterTargets="Publish">
     <PropertyGroup>
+      <!-- <ZipPublishDir_AppendVariantArgs>true</ZipPublishDir_AppendVariantArgs> -->
+      <!-- "C:/Repos/HaloSPV3/HXE" -->
       <RepoRoot>$([System.IO.Path]::GetDirectoryName($([MSBuild]::GetPathOfFileAbove('.gitignore', '$(MSBuildProjectDirectory)'))))</RepoRoot>
-      <Destination>$(RepoRoot)/publish/$(AssemblyName).$(Version)$(PART_RuntimeIdentifier)</Destination>
-      <Destination Condition="'$(RuntimeIdentifier)' != '' ">$(Destination).$(RuntimeIdentifier)</Destination>
+      <!-- " (net6.0 win7-x86)" -->
+      <!-- <PART_VariantArgs Condition="$(ZipPublishDir_AppendVariantArgs)"> ($([System.String]::Join(' ', $(TargetFramework), $(RuntimeIdentifier))))</PART_VariantArgs> -->
+      <PART_VariantArgs> ($([System.String]::Join(' ', $(TargetFramework), $(RuntimeIdentifier))))</PART_VariantArgs>
+      
+      <!-- e.g. "C:/Repos/HaloSPV3/HXE/publish/HXE 1.2.3-preview.4 (net6.0 win7-x86).zip" -->
+      <Destination>$(RepoRoot)/publish/$(AssemblyName) $(Version)$(PART_VariantArgs).zip</Destination>
     </PropertyGroup>
 
-    <!-- https://www.nuget.org/packages/GitInfo -->
+    <MakeDir Directories="$(RepoRoot)/publish/"/>
 
     <ZipDirectory
       SourceDirectory="$(PublishDir)"
-      DestinationFile="$(Destination).zip"
+      DestinationFile="$(Destination)"
       Overwrite="true" />
   </Target>
 </Project>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halospv3/hce.shared-config",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Automate commit message quality, changelogs, and CI/CD releases. Exports a semantic-release shareable configuration deserialized from this package's '.releaserc.yml'. Shared resources for .NET projects are also distributed with this package.",
   "keywords": [
     "halo",
@@ -44,7 +44,8 @@
     "@commitlint/cli": "^19.2.0",
     "@commitlint/config-conventional": "^19.1.0",
     "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/commit-analyzer": "^12.0.0",
+    "@semantic-release/exec": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^10.0.2",
     "@semantic-release/npm": "^12.0.0",

package/static/.releaserc.yml

@@ -20,13 +20,17 @@ plugins: # https://semantic-release.gitbook.io/semantic-release/v/beta/usage/con
     - assets:
         - README.md
         - CHANGELOG.md
+  # Arbitrary shell commands - https://github.com/semantic-release/exec
+  # hint: set 'prepareCmd' to `dotnet publish`. This can be a top-level property!
+  #   Because this is sorted after @semantic-release/git, the new Git tag will 
+  #   be visible to dotnet (and GitVersion). Dotnet artifacts will be
+  #   versioned accordingly.
+  # Plugins' Steps: https://github.com/semantic-release/semantic-release/blob/master/docs/extending/plugins-list.md
+  - "@semantic-release/exec"
   - - "@semantic-release/github"
     - assets:
         - path: ./publish/*
-## (OPTIONAL) update Version strings
+
+## (OPTIONAL) update static Version strings.
 # https://github.com/jpoehnelt/semantic-release-replace-plugin
 # https://github.com/droidsolutions/semantic-release-update-file
-
-## Arbitrary shell commands
-# (useful for `dotnet publish publish/`, but should be run after version tag is pushed so InformationalVersionInfo isn't a subversion)
-# https://github.com/semantic-release/exec