ci: type checking setup (mypy)

A hatch-based environment (`types`) is added.

Locally, hatch users can run

```
hatch run types:check
```

to get the checked out code type-checked.

Additionally, two workflows are added that test for typing issues.
One (`mypy-pr`) only tests files that changed in a PR. The other
(`mypy-project`) tests all code. The rational for having two separate
tests is that individual PRs should not be blocked by typing issues
that appear in the rest of the code base. This can happen when changes
are forced into the mainline, or conditions change between (Python)
versions.

.github/workflows/mypy-pr.yml

@@ -0,0 +1,41 @@
+name: Type annotation (PR)
+
+on:
+  pull_request:
+    paths:
+      - 'datalad_core/**.py'
+      - '!**/tests/**.py'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          # run on a "fresh" python, but see mypy flag to check for the oldest supported version
+          python-version: 3.12
+          architecture: x64
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install hatch (which pull mypy)
+        run: python -m pip install hatch
+      - name: Get Python changed files
+        id: changed-py-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            *.py
+            **/*.py
+      - name: Type check changed files
+        if: steps.changed-py-files.outputs.any_changed == 'true'
+        run: |
+          # get any type stubs that mypy thinks it needs
+          hatch run types:mypy --install-types --non-interactive --follow-imports skip ${{ steps.changed-py-files.outputs.all_changed_files }}
+          # run mypy on the modified files only, and do not even follow imports.
+          # this results is a fairly superficial test, but given the overall
+          # state of annotations, we strive to become more correct incrementally
+          # with focused error reports, rather than barfing a huge complaint
+          # that is unrelated to the changeset someone has been working on.
+          # run on the oldest supported Python version
+          hatch run types:mypy --python-version 3.9 --follow-imports skip --pretty --show-error-context ${{ steps.changed-py-files.outputs.all_changed_files }}

.github/workflows/mypy-project.yml

@@ -0,0 +1,29 @@
+name: Type annotation (project)
+
+on:
+  push:
+    paths:
+      - 'datalad_core/**.py'
+      - '!**/tests/**.py'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          # run on a "fresh" python, but see mypy flag to check for the oldest supported version
+          python-version: 3.12
+          architecture: x64
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install hatch (which pull mypy)
+        run: python -m pip install hatch
+      - name: Type check project
+        run: |
+          # get any type stubs that mypy thinks it needs
+          hatch run types:mypy --install-types --non-interactive --follow-imports skip datalad_core
+          # run mypy on the full project.
+          # run on the oldest supported Python version
+          hatch run types:mypy --python-version 3.9 --pretty --show-error-context datalad_core

datalad_core/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

pyproject.toml

@@ -56,6 +56,17 @@ extra-dependencies = [
   # https://github.com/pypa/hatch/issues/1565#issuecomment-2163773123
   "pytest-cov",
 ]
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+  "pytest",
+]
+[tool.hatch.envs.types.scripts]
+check = [
+  "mypy --install-types --non-interactive --python-version 3.9 --pretty --show-error-context datalad_core",
+]
+
 [tool.hatch.envs.docs]
 extra-dependencies = [
   "sphinx",
@@ -126,10 +137,31 @@ quote-style = "single"
 
 [tool.commitizen]
 name = "cz_customize"
+tag_format = "v$version"
+version_scheme = "pep440"
+version_provider = "scm"
+changelog_incremental = true
+template = ".changelog.md.j2"
+gpg_sign = true
 
 [tool.commitizen.customize]
 commit_parser = "^((?P<change_type>feat|fix|rf|perf|test|doc|BREAKING CHANGE)(?:\\((?P<scope>[^()\r\n]*)\\)|\\()?(?P<breaking>!)?|\\w+!):\\s(?P<message>.*)?(?P<body>.*)?"
 change_type_order = ["BREAKING CHANGE", "feat", "fix", "rf", "perf", "doc", "test"]
+changelog_pattern = "^((BREAKING[\\-\\ ]CHANGE|\\w+)(\\(.+\\))?!?):"
+bump_pattern = "^((BREAKING[\\-\\ ]CHANGE|\\w+)(\\(.+\\))?!?):"
 schema_pattern = "(?s)(ci|doc|feat|fix|perf|rf|style|test|chore|revert|bump)(\\(\\S+\\))?!?:( [^\\n\\r]+)((\\n\\n.*)|(\\s*))?$"
 
+[tool.commitizen.customize.bump_map]
+"^\\w+!" = "MAJOR"
+"^BREAKING" = "MAJOR"
+"^feat" = "MINOR"
+"^fix" = "PATCH"
 
+[tool.commitizen.customize.change_type_map]
+"BREAKING CHANGE" = "Breaking changes"
+doc = "Documentation"
+feat = "New features"
+fix = "Bug Fixes"
+test = "Tests"
+rf = "Refactorings"
+perf = "Performance improvements"