HCE.Shared

Infrastructure resources shared with other HaloSPV3 repositories.

It is recommended to "install" this repo via Node Package Manager

Usage

1. Install @halospv3/hce.shared-config

This project is packaged and published via NPM. As such...

npm install --save-dev @halospv3/hce.shared-config

2. Customize Semantic Release

WARNING! Defining a property will overwrite the previous value. Arrays and objects are not merged. You can...

• Assign to certain top-level variables (e.g. options.preset) to avoid modifying the plugins array. Caveat: only some plugins read these properties.
• Write your config in MJS; It is recommended you use deepmerge to recursively merge objects and arrays instead of using extends. Doing so will allow your IDE to tell you when a shareable config cannot be found.

Base Config

• Uses the conventionalcommits preset.
• Releases main branch; Pre-releases develop.
• Adds and configures semantic-release-export-data to export new-release-published and new-release-version to GitHub Actions' outputs.
• Adds and configures @semantic-release/changelog to update CHANGELOG.md.
• Configures @semantic-release/git to add README.md and CHANGELOG.md in a release commit if they have changes. Uses GitHub job's token to commit.
• Configures @semantic-release/github to release all files found in $PWD/publish.

Usage

// releaserc.config.js
import hceSharedConfig from "@halospv3/hce.shared-config"

// modify it however you wish before the export statement!

export default hceSharedConfig;

// releaserc.config.js
export default {
	extends: ["@halospv3/hce.shared-config"]
}

// package.json
{
	"release": {
		"extends": ["@halospv3/hce.shared-config"]
	}
}

Dotnet Config

An extension of our base config. Exports a function with parameters for 'projects to pack' and 'projects to push (to nuget)'. Although @halospv3/hce.shared-config/semanticReleaseConfigDotnet can be used via extends and configured via the PROJECTS_TO_PUBLISH and PROJECTS_TO_PACK_AND_PUSH environment variables, it is recommended to call the function and pass it parameters so errors are caught before they reach production.

Differences to the base config:

• Utilizes @semantic-release/exec for shell commands.
  • Executes dotnet publish and dotnet pack upon the configured projects during the prepare step.
  • (WIP) Executes dotnet nuget sign during prepare upon the dotnet pack outputs if projectsToPackAndPush is not set to false (default: []).
  • Executes dotnet nuget push during the publish step.

Usage

// releaserc.config.js
import { getConfig } from "@halospv3/hce.shared-config/semanticReleaseConfigDotnet"

/* Caveat: semantic-release will version and release all specified projects under the same Git tags and GitHub releases.
 * To version and release them separately, use [https://github.com/pmowrer/semantic-release-monorepo](semantic-release-monorepo).
 */

/* `prepareCmd` will contain command lines to publish 
 * both Library and Sample to your GitHub release.
 * Their `TargetFrameworks` and `RuntimeIdentifiers`
 * properties will be evaluated and a command line 
 * will be added for each unique combination, 
 * _regardless of compatibility and intended combinations_.
 */
const projectsToPublish = [
	"./Library/Library.csproj",
	"./Sample/Sample.csproj"
];
/*
 * `prepareCmd` will also contain `dotnet pack` and
 * `dotnet nuget sign` commands to pack Library to a nupkg.
 * `publishCmd` will contain `dotnet nuget push` commands
 *  to push Library to Nuget.org and GitHub Package Registry.
 */
const projectsToPackAndPush = ["./Library/Library.csproj"];

// runs getConfig and exports its return value
export default getConfig(projectsToPublish, projectsToPackAndPush)

extends key in a javascript config file

Using extends is NOT recommended, but I won't stop you. Your projects' paths must be assigned to environment variables. See Dotnet Config.

// releaserc.config.js (if {"type": "module"} in package.json)
export default {
	extends: ["@halospv3/hce.shared-config"]
}

// releaserc.config.js (if {"type": "commonjs"} in package.json)
module.exports = {
	extends: ["@halospv3/hce.shared-config"]
}

release key in package.json

// package.json
// `npm install --save-dev cross-env`
{
	"scripts":{
		"release":"cross-env PROJECTS_TO_PUBLISH=\"./Library/Library.csproj;./Sample/Sample.csproj\" semantic-release"
	},
	"release": {
		"extends": ["@halospv3/hce.shared-config/semanticReleaseConfigDotnet"]
	}
}

Notable Plugin Properties

• @semantic-release/commit-analyzer
  • preset (set to conventionalcommits)
  • parserOpts
  • releaseRules
• @semantic-release/release-notes-generator
  • preset (set to conventionalcommits)
  • parserOpts
  • writerOpts
• @semantic-release/changelog
  • changelogFile (default: 'CHANGELOG.md')
• @semantic-release/git
  • assets (default: ['README.md', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'])
• @semantic-release/exec
  • prepareCmd
• @semantic-release/github
  • assets
  • draftRelease (default: false)

3. Set Up CommitLint

// package.json
{
	"commitlint": {
		"extends": ["@halospv3/hce.shared-config/commitlintConfig"]
	}
}

or

/* eslint-disable import/no-default-export */
import commitlintConfig from '@halospv3/hce.shared-config/commitlintConfig';

export default commitlintConfig;

Then...

npx husky
npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'

4. (dotnet) Add/Edit Directory.Build.props

<Project>
	<Import Project="$(HCESharedDir)/dotnet/HCE.Shared.targets"/>

	<PropertyGroup>
		<RepoRoot Condition="'$(RepoRoot)' == ''">$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), '.git/index'))</RepoRoot>
		<HCESharedDir Condition="'$(HCESharedDir)' == ''">$(RepoRoot)node_modules/@halospv3/hce.shared-config/</HCESharedDir>
		<!--<GitVersion_Path Condition="'$(GitVersion_Path)' == ''">Path/To/Your/GitVersion.yml</GitVersion_Path>-->
	</PropertyGroup>
</Project>

These may evaluate to the following: | Property | Evaluated Value| | ------------ | -------------- | |RepoRootDir | c:\Repos\HaloSPV3\HCE.Shared\ | |HCESharedDir| c:\Repos\HaloSPV3\HCE.Shared\node_modules\@halospv3\hce.shared-config\ |

CI/CD-Only Properties

Note: Already included when importing HCE.Shared.targets If you don't import HCE.Shared.targets, you may import HCE.Shared.CI.props or define your own conditional property group.

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:

<Project>
	<PropertyGroup>
		...
	</PropertyGroup>

	<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

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, you can configure GitVersion to use this config file. GitVersion does not have 'extend' functionality typical of Node.js packages.

You can...

...define it yourself

<Project>
	<PropertyGroup>
		<GitVersion_Path>$(ProjectRootDir)/node_modules/@halospv3/hce.shared-config/dotnet/GitVersion.yml</GitVersion_Path>
	</PropertyGroup>
</Project>

...import HCE.Shared.props

<Project>
	<Import Project="$(HCESharedDir)/dotnet/HCE.Shared.props">
</Project>

...import HCE.Shared.Targets (which imports HCE.Shared.props)

<Project>
	<Import Project="$(HCESharedDir)/dotnet/HCE.Shared.props">
</Project>

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.

Run the following to preview the version:

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 will export the next version and other information as GitHub Action Step outputs.

Don't intend to publish a Node package?

Add the following to package.json:

{
	"private": true,
}

WIP

Reusable, configurable GitHub workflows

See callable workflows such as dotnet-ci

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