build: Switch to using pre-commit

Author: Alan Christie

.cz.yaml

@@ -0,0 +1,46 @@
+---
+# Commitizen custom configuration.
+# Here we extend it to add all our recognised types into the changelog.
+# The default ignores pretty-much anything other than 'feat' and 'fix'.
+#
+# See the default at...
+# https://github.com/commitizen-tools/commitizen/
+#   blob/095f02e6c419b60c90aa84b8cebc9e9eacc8a391/commitizen/defaults.py#L83
+commitizen:
+  name: cz_customize
+  # What's the first revision we're interested imn?
+  # For us it's the revision we started using
+  # enforcing the use of conventional commits.
+  # Prior to 19.1.0 we weren't using it on every commit
+  # and didn't have everything ready for change-logs.
+  changelog_start_rev: 19.1.0
+  customize:
+    schema_pattern: "^(?P<change_type>feat|fix|perf|refactor|style|test|build|docs|ci|BREAKING CHANGE)(?:\\((?P<scope>[^()\\r\\n]*)\\)|\\()?(?P<breaking>!)?:\\s(?P<message>.*)?"
+    commit_parser: "^(?P<change_type>feat|fix|perf|refactor|style|test|build|docs|ci|BREAKING CHANGE)(?:\\((?P<scope>[^()\\r\\n]*)\\)|\\()?(?P<breaking>!)?:\\s(?P<message>.*)?"
+    # The changelog_pattern identifies the commit types
+    # that will be included.
+    # Build the changelog with 'cz ch' on the staging or production branches.
+    changelog_pattern: "^(feat|fix|perf|refactor|style|test|build|docs|ci)?"
+    # A mapping of type to its group name in the changelog.
+    # We call 'feat' commits 'New Features'
+    change_type_map:
+      build: Build
+      docs: Documentation
+      feat: New Features
+      fix: Bug Fixes
+      perf: Performance Improvements
+      refactor: Refactoring
+      style: Stylistic Changes
+      ci: CI/CD
+      test: Testing
+    # The order of commit types in the changelog...
+    change_type_order:
+    - "feat"
+    - "fix"
+    - "perf"
+    - "refactor"
+    - "style"
+    - "test"
+    - "build"
+    - "ci"
+    - "docs"

.github/workflows/build-latest.yaml

@@ -42,8 +42,7 @@ jobs:
         ansible-galaxy install -r requirements.yaml
     - name: Lint
       run: |
-        yamllint .
-        find . -type f -name '*.yaml.j2' -exec yamllint {} +
+        pre-commit run --all-files
         ansible-lint
     - name: Login to DockerHub
       uses: docker/login-action@v1

.github/workflows/build.yaml

@@ -44,8 +44,7 @@ jobs:
         ansible-galaxy install -r requirements.yaml
     - name: Lint
       run: |
-        yamllint .
-        find . -type f -name '*.yaml.j2' -exec yamllint {} +
+        pre-commit run --all-files
         ansible-lint
     - name: Build
       uses: docker/build-push-action@v2

.pre-commit-config.yaml

@@ -0,0 +1,60 @@
+---
+minimum_pre_commit_version: 2.18.1
+exclude: ^(docs|tests|example-data|migrations|unit-test-data|VERSION)
+
+repos:
+
+# commit-msg hooks
+# ----------
+
+# Conventional Commit message checker (commitizen)
+- repo: https://github.com/commitizen-tools/commitizen
+  rev: master
+  hooks:
+  - id: commitizen
+    stages:
+    - commit-msg
+
+# pre-commit hooks
+# ----------
+
+# Standard pre-commit rules
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.1.0
+  hooks:
+  - id: check-case-conflict
+  - id: check-docstring-first
+  - id: check-executables-have-shebangs
+  - id: check-shebang-scripts-are-executable
+  - id: detect-private-key
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+    args:
+    - --markdown-linebreak-ext=md
+# Black (uncompromising) Python code formatter
+- repo: https://github.com/psf/black
+  rev: 22.3.0
+  hooks:
+  - id: black
+    args:
+    - --target-version
+    - py310
+# MyPy
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v0.942
+  hooks:
+  - id: mypy
+    files: ^operator
+# YAML Lint
+# We have to adjust this hook, whcih looks for yaml files,
+# because some of our files are 'disguised' and not found by
+# 'identify', used by pre-commit. So we basically say...
+# All files that end '.yaml' or '.yaml.j2'
+# See https://pre-commit.com/#filtering-files-with-types
+- repo: https://github.com/adrienverge/yamllint
+  rev: v1.26.3
+  hooks:
+  - id: yamllint
+    types:
+    - file
+    files: (\.yaml|\.yaml.j2)$

README.md

@@ -9,6 +9,10 @@
 
 ![GitHub tag (latest SemVer pre-release)](https://img.shields.io/github/v/tag/informaticsmatters/data-manager-jupyter-operator?include_prereleases)
 
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
 This repo contains a Kubernetes _Operator_ based on the [kopf] and [kubernetes]
 Python packages that is used by the **Informatics Matters Data Manager API**
 to create Jupyter Notebooks for the Data Manager service.
@@ -22,10 +26,32 @@ By default, the operator creates instances using the Jupyter image: -
 
 Prerequisites: -
 
--   Python (ideally 3.9.x)
+-   Python
 -   Docker
 -   A kubernetes config file
 
+## Contributing
+The project uses: -
+
+- [pre-commit] to enforce linting of files prior to committing them to the
+  upstream repository
+- [Commitizen] to enforce a [Convention Commit] commit message format
+- [Black] as a code formatter
+
+You **MUST** comply with these choices in order to  contribute to the project.
+
+To get started review the pre-commit utility and the conventional commit style
+and then set-up your local clone by following the **Installation** and
+**Quick Start** sections: -
+
+    pip install -r build-requirements.txt
+    pre-commit install -t commit-msg -t pre-commit
+
+Now the project's rules will run on every commit, and you can check the
+current health of your clone with: -
+
+    pre-commit run --all-files
+
 ## Building the operator (local development)
 The operator container, residing in the `operator` directory,
 is automatically built and pushed to Docker Hub using GitHub Actions.
@@ -183,6 +209,10 @@ Both are exposed in the example parameter file `example-parameters.yaml`.
 
 [ansible]: https://www.ansible.com
 [ansible galaxy]: https://galaxy.ansible.com
+[black]: https://black.readthedocs.io/en/stable
 [certificate manager]: https://cert-manager.io/docs/installation/kubernetes/
+[commitizen]: https://commitizen-tools.github.io/commitizen/
+[conventional commit]: https://www.conventionalcommits.org/en/v1.0.0/
 [kopf]: https://pypi.org/project/kopf/
 [kubernetes]: https://pypi.org/project/kubernetes/
+[pre-commit]: https://pre-commit.com

build-requirements.txt

@@ -1,2 +1,5 @@
-ansible-lint
-yamllint
+ansible-lint == 6.0.2
+black == 22.3.0
+mypy == 0.942
+pre-commit == 2.18.1
+yamllint == 1.26.3