feat(action): Create docker-cache GitHub Action

Cache Docker images whether built or pulled. Write documentation for
users in README.md and for contributors in CONTRIBUTING.md. Configure
many YAML, Markdown, TOML, polyglot, natural language, Git, and
pre-commit hooks written in Python via pre-commit. Setup Poetry with
Commitizen and pre-commit as dev dependencies. Add VSCode settings, and
recommend extensions. Create workflow to automatically bump SemVer,
populate CHANGELOG.md, and tag versions.

.dictionary.txt

@@ -0,0 +1 @@
+Laven

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.gitattributes

@@ -0,0 +1,7 @@
+# Normalize line endings of all text files to LF when adding or committing
+# them to the repository.
+* text=auto
+
+# Normalize line endings of all text files to LF when copying them from the
+# repository to the working directory, such as when checking them out.
+* text eol=lf

.github/workflows/bump-version.yaml

@@ -0,0 +1,12 @@
+name: Bump Version
+on:
+  push:
+    branches:
+      - main
+jobs:
+  bump-version:
+    name: Bump Version
+    uses: ScribeMD/slack-templates/.github/workflows/[email protected]
+    secrets:
+      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+      SLACK_ACTIONS_CHANNEL_ID: ${{ secrets.SLACK_ACTIONS_CHANNEL_ID }}

.github/workflows/notify-assignee.yaml

@@ -0,0 +1,12 @@
+name: Notify Assignee
+on:
+  pull_request:
+    types:
+      - assigned
+jobs:
+  notify-assignee:
+    name: Notify Assignee
+    uses: ScribeMD/slack-templates/.github/workflows/[email protected]
+    secrets:
+      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+      SLACK_ASSIGN_CHANNEL_ID: ${{ secrets.SLACK_ASSIGN_CHANNEL_ID }}

.github/workflows/notify-reviewers.yaml

@@ -0,0 +1,12 @@
+name: Notify Reviewers
+on:
+  pull_request:
+    types:
+      - review_requested
+jobs:
+  notify-reviewers:
+    name: Notify Reviewers
+    uses: ScribeMD/slack-templates/.github/workflows/[email protected]
+    secrets:
+      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+      SLACK_REVIEW_CHANNEL_ID: ${{ secrets.SLACK_REVIEW_CHANNEL_ID }}

.github/workflows/test.yaml

@@ -0,0 +1,15 @@
+name: Test
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+jobs:
+  test:
+    name: Run Pre-commit Hooks
+    uses: ScribeMD/pre-commit-action/.github/workflows/[email protected]
+    secrets:
+      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+      SLACK_ACTIONS_CHANNEL_ID: ${{ secrets.SLACK_ACTIONS_CHANNEL_ID }}

.gitignore

@@ -0,0 +1,5 @@
+# MegaLinter
+report/
+
+# Poetry
+.venv

.jscpd.json

@@ -0,0 +1,10 @@
+{
+  "maxLines": 0,
+  "maxSize": 0,
+  "threshold": 0,
+  "reporters": ["consoleFull", "console"],
+  "ignore": [".git", ".venv"],
+  "gitignore": true,
+  "blame": true,
+  "ignoreCase": true
+}

.markdownlint.yaml

@@ -0,0 +1,3 @@
+# Commitizen produces duplicate headings in CHANGELOG.md.
+no-duplicate-header:
+  siblings_only: true

.mega-linter.yaml

@@ -0,0 +1,12 @@
+APPLY_FIXES: all
+DEFAULT_BRANCH: main
+FAIL_IF_MISSING_LINTER_IN_FLAVOR: true
+FORMATTERS_DISABLE_ERRORS: false
+PRINT_ALPACA: false
+SHOW_ELAPSED_TIME: true
+CREDENTIALS_SECRETLINT_ARGUMENTS: --secretlintignore .gitignore
+JSON_PRETTIER_FILE_EXTENSIONS:
+  - .json
+  - .md
+MARKDOWN_MARKDOWNLINT_CONFIG_FILE: .markdownlint.yaml
+SPELL_CSPELL_CONFIG_FILE: LINTER_DEFAULT

.pre-commit-config.yaml

@@ -0,0 +1,98 @@
+default_install_hook_types:
+  - commit-msg
+  - post-checkout
+  - pre-commit
+  - pre-merge-commit
+  - pre-push
+default_language_version:
+  python: python3.10.4
+default_stages:
+  - commit
+  - push
+minimum_pre_commit_version: 2.18.1
+repos:
+  # Automatically fix issues.
+
+  ## Python, Polyglot, Git, pre-commit
+  - repo: https://github.com/ScribeMD/pre-commit-hooks
+    rev: 0.3.0
+    hooks:
+      - id: no-merge-commits
+      - id: asdf-install
+      - id: poetry-check
+      - id: poetry-lock
+      - id: poetry-install
+      - id: pre-commit-install
+      - id: megalinter
+        args: &megalinter-args [--flavor, documentation, --release, v5.11.0]
+      - id: megalinter-all
+        args: *megalinter-args
+
+  ## Markdown
+  - repo: https://github.com/frnmst/md-toc
+    rev: 8.1.2
+    hooks:
+      - id: md-toc
+
+  ## Python, TOML, Polyglot, Git
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.2.0
+    hooks:
+      ### Automatically fix issues.
+      - id: end-of-file-fixer
+      - id: file-contents-sorter
+        files: \.dictionary\.txt
+        args: [--ignore-case, --unique]
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+      ### Check for issues.
+      - id: check-added-large-files
+        args: [--enforce-all]
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-shebang-scripts-are-executable
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-vcs-permalinks
+      - id: destroyed-symlinks
+      - id: detect-aws-credentials
+        args: [--allow-missing-credentials]
+      - id: detect-private-key
+      - id: forbid-new-submodules
+      - id: no-commit-to-branch
+
+  # Check for issues.
+
+  ## Pre-commit
+  - repo: meta
+    hooks:
+      - id: check-useless-excludes
+
+  ## Python
+  - repo: https://github.com/Lucas-C/pre-commit-hooks-safety
+    rev: v1.2.4
+    hooks:
+      - id: python-safety-dependencies-check
+
+  ## Natural language
+  - repo: https://github.com/PrincetonUniversity/blocklint
+    rev: v0.2.3
+    hooks:
+      - id: blocklint
+
+  ## Git
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v2.24.0 # Keep in sync with pyproject.toml.
+    hooks:
+      - id: commitizen
+        stages:
+          - commit-msg
+  - repo: https://github.com/jumanjihouse/pre-commit-hooks
+    rev: 2.1.6
+    hooks:
+      - id: check-mailmap
+      - id: forbid-binary
+      - id: git-check

.tool-versions

@@ -0,0 +1,3 @@
+nodejs 16.14.2
+python 3.10.4
+poetry 1.1.13

.vscode/extensions.json

@@ -0,0 +1,11 @@
+{
+  "recommendations": [
+    "davidanson.vscode-markdownlint",
+    "editorconfig.editorconfig",
+    "esbenp.prettier-vscode",
+    "ms-azuretools.vscode-docker",
+    "ms-vscode-remote.remote-containers",
+    "redhat.vscode-yaml",
+    "streetsidesoftware.code-spell-checker"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "editor.tabSize": 2,
+  "editorconfig.generateAuto": false,
+  "files.eol": "\n",
+  "files.insertFinalNewline": true,
+  "files.trimTrailingWhitespace": true,
+  "python.defaultInterpreterPath": "./.venv/bin/python",
+  "python.terminal.activateEnvInCurrentTerminal": true,
+  "search.exclude": {
+    "poetry.lock": true
+  }
+}

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+This changelog is auto-generated by the Python-based
+[commitizen](https://commitizen-tools.github.io/commitizen).
+

CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing Guide
+
+See [CONTRIBUTING.md of ScribeMD/slack-templates](https://github.com/ScribeMD/slack-templates/blob/main/CONTRIBUTING.md).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 ScribeMD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,64 @@
+# docker-cache
+
+[![Test](https://github.com/ScribeMD/docker-cache/workflows/Test/badge.svg)](https://github.com/ScribeMD/docker-cache/actions/workflows/test.yaml)
+[![Bump Version](https://github.com/ScribeMD/docker-cache/workflows/Bump%20Version/badge.svg)](https://github.com/ScribeMD/docker-cache/actions/workflows/bump-version.yaml)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square)](https://conventionalcommits.org)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+
+Cache Docker Images Whether Built or Pulled
+
+<!--TOC-->
+
+- [docker-cache](#docker-cache)
+  - [Usage](#usage)
+  - [Inputs](#inputs)
+    - [Required](#required)
+  - [Supported Runners](#supported-runners)
+  - [Contributing](#contributing)
+  - [Changelog](#changelog)
+
+<!--TOC-->
+
+[Use Docker in rootless mode](https://github.com/ScribeMD/rootless-docker) to
+avoid permission issues. Query the Docker root directory via
+[`docker info`](https://docs.docker.com/engine/reference/commandline/info/), so
+it can be cached. This is where Docker stores both built and pulled images. Note
+that this action does not perform Docker layer caching.
+[The official Docker build push action](https://github.com/docker/build-push-action)
+performs Docker layer caching for built images but does not cache pulled images.
+
+## Usage
+
+- Add the following step before your first use of Docker:
+
+```yaml
+- name: Cache Docker images.
+  uses: ScribeMD/[email protected]
+  with:
+    key: docker-${{ runner.os }}-${{ hashFiles(...) }}
+```
+
+## Inputs
+
+### Required
+
+#### `key`
+
+The explicit cache key to ferry to the
+[official GitHub cache action](https://github.com/marketplace/actions/cache).
+`restore-keys` are not supported, because partial cache restoration leads to a
+["snowball" effect](https://glebbahmutov.com/blog/do-not-let-npm-cache-snowball/).
+
+## Supported Runners
+
+Please refer to
+[README.md of ScribeMD/rootless-docker](https://github.com/ScribeMD/rootless-docker#supported-runners).
+
+## Contributing
+
+Please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Changelog
+
+Please refer to [CHANGELOG.md](CHANGELOG.md).

action.yaml

@@ -0,0 +1,29 @@
+name: Docker Cache
+author: Kurt von Laven
+description: Cache Docker images whether built or pulled.
+branding:
+  icon: download
+  color: blue
+inputs:
+  key:
+    description: >
+      The cache key to ferry to the official GitHub cache action. restore-keys
+      are not supported, because partial cache restoration leads to a "snowball"
+      effect.
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Use Docker in rootless mode.
+      uses: ScribeMD/[email protected]
+    - name: Get Docker root directory.
+      id: docker-info
+      run: |
+        docker_root_dir="$(docker info --format "{{ .DockerRootDir }}")"
+        echo "::set-output name=root-dir::$docker_root_dir"
+      shell: bash
+    - name: Cache Docker images.
+      uses: actions/[email protected]
+      with:
+        path: ${{ steps.docker-info.outputs.root-dir }}
+        key: ${{ inputs.key }}

cspell.config.yaml

@@ -0,0 +1,13 @@
+version: "0.2"
+language: en-US
+useGitignore: true
+ignorePaths:
+  - .vscode
+dictionaryDefinitions:
+  - name: custom
+    path: .dictionary.txt
+dictionaries:
+  - custom
+  - fullstack
+  - npm
+  - python