Add sample/example projects

[BinToss]

Basic scenarios: override of properties whose names are only in one plugin config. Or no configuration aside from what's inherited from this shareable config. "Static" YAML/JSON config.

Advanced scenarios: piecemeal and/or independent modification of plugins' settings. CJS config.

Pros And Cons Of Configuration File/Data Format

The dependent project can use any format for its own configuration as long as the format is supported by Semantics Release e.g. YAML, JSON, release object property in package.json, CJS.

"Static" configs (YAML, JSON) can be easier to learn to read and write, but overriding values provided by this shareable config will be limited in capability. As it stands, you cannot add to or modify the plugin array inherited by a static config. If you wish to override a property in a plugin's configuration, you can use add a custom property in the releaserc object. However, this new property will override the value of every plugin config property with the same name. The Git and GitHub plugins' configurations both have an assets property. A top-level assets property will override the assets for both plugins which is usually undesirable. One is for committing files and the other is for adding files to a GitHub Release.

"Dynamic" configs are limited to the old "CJS" JavaScript format¹. Despite this, JavaScript allows for far more flexibility...and far more complexity and human error. Transpiling a TypeScript source file allows for better IntelliSense and code validation, but increases project complexity for what was just a small and simple framework for automatic versioning, packaging, and releases.

¹ At the time of this writing, Semantic Release cannot load ESM (EcmaScript) shareable confgurations.

Multiple Ways To Consume This Library

• NPM/Yarn (recommended)
• Git SubModule (still requires NPM or Yarn with the local path to this package so Semantics Release can find it)
• File-directory copy without version tracking e.g. downloading a commit or release package and copying it elsewhere (NOT recommended)

Notes

• https://github.com/BinToss/GroupBox.Avalonia has a .releaserc.js containing a commented section of code. This snippet details how to add to or modify the plugins/plugins-confguration array without accidentally decimating existing items in the array. Adding another layer of complexity is the array's mixed item type. The array can contain both strings and pseudo-tuples (2-item arrays) representing key-value pairs of a plugin name and the plugin's configuration object. Lots of square brackets. Lots of curly braces. Lovely. Why not have a string[] property for plugin names to load and then one additional object property for each plugin's configuration object?

{
...
  "plugins": ["plugin1", "plugin2"],
  "plugin1": {
    "op": "merge",
    "config": {}
  },
  "plugin2": {
    "op": "override",
    "config": {}
  }
}

releaserc.plugins.map((plugin) => loadPluginConfigs(releaserc[plugin]))

Still limited in capability unless the T | {op,T} type architecture is supported by and used throughout each plugin...or a custom handler/loader plugin loaded first.