docs: add custom-plugins example

custom-plugins/README.md

+# Custom Plugins
+
+This example shows how to create a custom semantic-release plugin without publishing it to the plugin index.
+
+## Setup
+
+Run `./build.sh`, this will build the hooks plugin and place it in the semantic-release plugin directory.
+
+## Run semantic-release
+
+```bash
+curl -SL https://get-release.xyz/semantic-release/$(go env GOOS)/$(go env GOARCH) -o ./semantic-release
+chmod +x ./semantic-release
+# enable the logger plugin
+./semantic-release --hooks logger
+```
+
+### Example Output
+
+```
+[go-semantic-release]: version: 2.10.0
+[go-semantic-release]: ci-condition plugin: GitHub Actions@1.2.0
+[go-semantic-release]: provider plugin: git@1.0.1
+[go-semantic-release]: getting default branch...
+[go-semantic-release]: found default branch: master
+[go-semantic-release]: found current branch: feature1
+[go-semantic-release]: found current sha: 8d9d13d
+[go-semantic-release]: hooks plugins: logger@dev
+[go-semantic-release]: running CI condition...
+[hooks-logger]: reason: CONDITION
+[hooks-logger]: message: This test run was triggered on the branch feature1, while semantic-release is configured to only publish from master.
+[go-semantic-release]: This test run was triggered on the branch feature1, while semantic-release is configured to only publish from master.
+```

custom-plugins/build.sh

+#!/bin/bash
+
+set -euo pipefail
+
+pluginDir=".semrel/$(go env GOOS)_$(go env GOARCH)/hooks-logger/1.0.0/"
+[[ ! -d "$pluginDir" ]] && {
+  echo "creating $pluginDir"
+  mkdir -p $pluginDir
+}
+
+go build -o $pluginDir/logger main.go

custom-plugins/main.go

+package main
+
+import (
+	"log"
+	"os"
+
+	"github.com/go-semantic-release/semantic-release/v2/pkg/hooks"
+	"github.com/go-semantic-release/semantic-release/v2/pkg/plugin"
+)
+
+type HooksLogger struct {
+	logger *log.Logger
+}
+
+func (t *HooksLogger) Init(m map[string]string) error {
+	return nil
+}
+
+func (t *HooksLogger) Name() string {
+	return "logger"
+}
+
+func (t *HooksLogger) Version() string {
+	return "dev"
+}
+
+func (t *HooksLogger) Success(config *hooks.SuccessHookConfig) error {
+	t.logger.Println("old version: " + config.PrevRelease.Version)
+	t.logger.Println("new version: " + config.NewRelease.Version)
+	t.logger.Printf("commit count: %d\n", len(config.Commits))
+	return nil
+}
+
+func (t *HooksLogger) NoRelease(config *hooks.NoReleaseConfig) error {
+	t.logger.Println("reason: " + config.Reason.String())
+	t.logger.Println("message: " + config.Message)
+	return nil
+}
+
+func main() {
+	plugin.Serve(&plugin.ServeOpts{
+		Hooks: func() hooks.Hooks {
+			return &HooksLogger{
+				logger: log.New(os.Stderr, "", 0),
+			}
+		},
+	})
+}

custom-plugins/run.sh

+#!/bin/bash
+
+set -euo pipefail
+
+[[ ! -f "./semantic-release" ]] && {
+  echo "downloading semantic-release..."
+  curl -SL https://get-release.xyz/semantic-release/$(go env GOOS)/$(go env GOARCH) -o ./semantic-release
+  chmod +x ./semantic-release
+}
+
+export GITHUB_REF="refs/heads/feature1"
+export GITHUB_SHA="8d9d13d"
+./semantic-release --dry --hooks logger --ci-condition github --provider git --provider-opt "git_path=../"

go.mod

+module github.com/go-semantic-release/examples
+
+go 1.15
+
+require github.com/go-semantic-release/semantic-release/v2 v2.10.0