build: Release and update CHANGELOG.md with release-it from workf…

…low (#164)

- Add `release-it` with its custom calver plugin
- Add `RELEASE.md`
- Add `release` scope and remove `dev` scope
- Add convention about Git workflow

.check.exs

@@ -31,6 +31,7 @@
     {:js_lint, "./run js:lint"},
     {:markdown_lint, "./run markdown:lint"},
     {:prettier_lint, "./run prettier:lint"},
+    {:release_test, "./run release:test"},
     {:shell_lint, "./run shell:lint"},
     {:spellcheck_lint, "./run spellcheck:lint"}
   ]

.commitlintrc.yml

@@ -16,7 +16,6 @@ rules:
       - config
       - deps
       - deps-dev
-      - dev
       - docker
       - git
       - lint
@@ -25,6 +24,7 @@ rules:
       - npm
       - license
       - readme
+      - release
       - security
       - scripts
       - vscode

.editorconfig

@@ -31,3 +31,6 @@ binary_next_line = true
 
 [*.md]
 trim_trailing_whitespace = false
+
+[*.hbs]
+insert_final_newline = false

.eslintignore

@@ -5,6 +5,9 @@
 node_modules/
 npm_cache/
 
+# release-it config file
+!.release-it.js
+
 # Elixir
 _build/
 cover/

.eslintrc.yml

@@ -22,4 +22,16 @@ extends:
   - plugin:unicorn/recommended
   - prettier # Must be last
 
-rules: { no-warning-comments: warn }
+rules:
+  {
+    import/no-extraneous-dependencies:
+      [error, { devDependencies: [./scripts/**/*.js, .release-it.js] }],
+    no-warning-comments: warn,
+  }
+
+overrides:
+  - files:
+      - ./scripts/**/*.js
+      - .release-it.js
+    rules:
+      unicorn/prefer-module: off

.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version-modifier:
+        description: "Version modifier; optional (dev, alpha, beta, rc)"
+        required: false
+
+jobs:
+  create-release:
+    name: Release
+    runs-on: ubuntu-20.04
+
+    steps:
+      - name: Check if main branch
+        if: ${{ github.ref != 'refs/heads/main' }}
+        uses: actions/[email protected]
+        with:
+          script: |
+            core.setFailed('Error: Release is possible only on the main branch')
+
+      - name: Checkout code
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+
+      - name: Setup git config
+        run: |
+          git config user.name "${GITHUB_ACTOR}"
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+      # —————————————————————————————————————————————— #
+      #                  Dependencies                  #
+      # —————————————————————————————————————————————— #
+
+      - name: Setup NodeJS
+        uses: actions/[email protected]
+        with:
+          node-version: 16
+          cache: npm
+          cache-dependency-path: "**/package-lock.json"
+
+      - name: Install node modules
+        run: npm ci --quiet
+
+      # —————————————————————————————————————————————— #
+      #                   Application                  #
+      # —————————————————————————————————————————————— #
+
+      - name: Update changelog, update all versions, tag and cut a release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE: true
+        run: |
+          ./run release:ci ${{ github.event.inputs.version-modifier }}

.gitignore

@@ -35,3 +35,6 @@ config/*.secret.exs
 
 # Keep .gitkeep files
 !/**/.gitkeep
+
+# Generated temporary files
+*.tmp

.husky/pre-commit

@@ -3,7 +3,9 @@
 # shellcheck source=.husky/_/husky.sh
 . "$(dirname "$0")/_/husky.sh"
 
-if [ -n "$INSIDE_DOCKER" ]; then
+if [ -n "$RELEASE" ]; then
+  npx lint-staged
+elif [ -n "$INSIDE_DOCKER" ]; then
   npx lint-staged
   mix check --only ex_unit
 else

.lintstagedrc.yml

@@ -38,7 +38,9 @@
   - ./run prettier:format
   - ./run prettier:lint
 
-"*.md":
+# CHANGELOG.md text is generated automatically.
+# Also, as the file grows, it will take longer to lint and format.
+"!(CHANGELOG).md":
   - ./run prettier:format
   - ./run prettier:lint
   - ./run markdown:lint

.markdownlintignore

@@ -5,6 +5,10 @@
 node_modules/
 npm_cache/
 
+# Text is generated automatically.
+# Also, as the file grows, it will take longer to lint and format.
+CHANGELOG.md
+
 # Elixir
 _build/
 cover/

.prettierignore

@@ -11,6 +11,10 @@ npm_cache/
 .eslintcache
 .stylelintcache
 
+# Text is generated automatically.
+# Also, as the file grows, it will take longer to lint and format.
+CHANGELOG.md
+
 # Elixir
 _build/
 cover/

.release-it.js

@@ -0,0 +1,55 @@
+// CalVer date tags 0Y, 0M, 0W and 0D are not supported by "@release-it/bumper"
+// and "@release-it/conventional-changelog".
+// Reason: Those plugins support semver only.
+
+const { readFileSync } = require('fs');
+const commitGroupsSort = require('./scripts/release-it/plugins/conventional-changelog/commit-groups-sort');
+const types = require('./scripts/release-it/types');
+
+const scriptsPath = './scripts/release-it';
+const hooksPath = `${scriptsPath}/hooks`;
+const pluginsPath = `${scriptsPath}/plugins`;
+const templatesPath = `${scriptsPath}/templates`;
+
+module.exports = {
+  git: {
+    // eslint-disable-next-line no-template-curly-in-string
+    commitMessage: 'chore: Release ${version}\n\n[skip ci]',
+    requireBranch: 'main',
+  },
+  github: {
+    release: true,
+  },
+  npm: false,
+  hooks: {
+    'before:conventional-changelog:beforeRelease': `bash ${hooksPath}/changelog/delete_header.sh`,
+    'after:conventional-changelog:beforeRelease': `bash ${hooksPath}/changelog/add_header.sh`,
+  },
+  plugins: {
+    '@release-it/bumper': {
+      in: {
+        file: 'VERSION',
+        type: 'text/plain',
+      },
+      out: [
+        {
+          file: 'VERSION',
+          type: 'text/plain',
+        },
+      ],
+    },
+    [`${pluginsPath}/calver-bumper.js`]: {},
+    '@release-it/conventional-changelog': {
+      infile: 'CHANGELOG.md',
+      ignoreRecommendedBump: true,
+      preset: {
+        name: 'conventionalcommits',
+        types,
+      },
+      writerOpts: {
+        headerPartial: readFileSync(`${templatesPath}/header.hbs`, 'utf-8'),
+        commitGroupsSort,
+      },
+    },
+  },
+};

.vscode/settings.json

@@ -188,6 +188,9 @@
   "[git-rebase]": {
     "editor.rulers": [100]
   },
+  "[handlebars]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
   "[html-eex]": {
     "editor.rulers": [120]
   },

CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+This file will be updated automatically.

RELEASE.md

@@ -0,0 +1,61 @@
+# Release
+
+Releases are cut from the `main` branch only.
+
+_Versioning convention_: [Calendar Versioning (CalVer)](https://calver.org/)
+_Format_: `YYYY.MM.MINOR`
+_Possible modifiers_:
+
+- Empty
+- `dev` for releases as development or prealpha
+- `alpha`
+- `beta`
+- `rc` for releases as release candidate
+
+Examples:
+
+- Empty modifier: `2021.11.64`
+- `alpha` modifier: `2021.11.64-alpha`
+
+## How to publish a release? 🤔
+
+1. Go to the repository on `github.com`
+1. Click on `Actions`
+1. Click on `Release`
+1. Click on `Run workflow`
+1. Choose a version modifier suffix (optional). Possible values:
+   - Let it empty for stable release. No modifier will be added.
+   - `dev` for releases as development or prealpha
+   - `alpha`
+   - `beta`
+   - `rc` for releases as release candidate
+1. Click on `Run workflow`
+
+This workflow uses [Release It!](https://github.com/release-it/release-it) to:
+
+- update `VERSION`
+- generate/update `CHANGELOG.md`
+- commit and push to git
+- attach assets to `Github Release`
+- create a `Github Release`
+
+## How `CHANGELOG.md` is updated? 📄
+
+`CHANGELOG.md` is automatically by the plugin
+[@release-it/conventional-changelog](https://github.com/release-it/conventional-changelog).
+
+Custom templates under `./scripts/release-it` control the header text of the
+file. The later has tag to distinguish the static header from the generated
+lines.
+
+## What is `VERSION`? 🤔
+
+It contains the latest version.
+
+In other words, it is the latest git tag. The version from this file is used to calculate
+the next version.
+
+This file and other files containing the application version are automatically
+updated by [@release-it/bumper](https://github.com/release-it/bumper).
+The later is supported by a custom `release-it` plugin (`calver-bumper.js`)
+which calculate the next `CalVer`.

VERSION

@@ -0,0 +1 @@
+2021.10.0

cspell.yml

@@ -79,28 +79,31 @@ overrides:
     languageId: "shellscript"
   - filename: "Dockerfile*"
     languageId: "dockerfile"
-  - filename: ".github/workflows/ci.yml"
+  - filename: ".github/workflows/*.yml"
     dictionaries:
       - bash
       - bash-custom
 
 ignorePaths:
   - "**/_build/**"
-  - "**/.git/**/!(COMMIT_EDITMSG)*"
-  - "**/.eslintcache"
   - "**/.elixir_ls/**"
+  - "**/.eslintcache"
+  - "**/.git/**/!(COMMIT_EDITMSG)*"
   - "**/.history/**"
   - "**/.husky/_/**"
-  - "**/.stylelintcache"
   - "**/.sobelow"
+  - "**/.stylelintcache"
   - "**/.vscode-insiders/**"
   - "**/cover/**"
   - "**/deps/**"
   - "**/doc/**"
   - "**/node_modules/**"
   - "**/npm_cache/**"
   - "**/package-lock.json"
-  - "**/priv/plts/*.plt"
   - "**/priv/plts/*.plt.hash"
+  - "**/priv/plts/*.plt"
   - "**/spellcheck/**"
   - "**/vscode-extension/**"
+  # Text is generated automatically.
+  # Also, as the file grows, it will take longer to lint and format.
+  - "CHANGELOG.md"

docs/code-convention.md

@@ -1,5 +1,12 @@
 # Code convention
 
+## Git workflow
+
+The follow git workflow is [Scaled Trunk-Based Development](https://trunkbaseddevelopment.com).
+
+1. `main` is the only long-lived branch
+1. All other branches are short-lived branches
+
 ## Git commit messages
 
 Commit messages must follow the specification from [Conventional Commits](https://www.conventionalcommits.org).
@@ -15,6 +22,8 @@ To help you to choose the right `type` or `scope`, you can commit:
 
 - Use `:` to separate scopes
 - Use `-` (kebab-case) for scope names or purposes
+- Use `_` (snake_case) for helper functions that should not directly be used by
+  the CLI
 
 ```shellscript
 function dev:dotnet-core:global-install {