Dev

.cz.yaml

@@ -0,0 +1,8 @@
+---
+commitizen:
+  major_version_zero: true
+  name: cz_conventional_commits
+  tag_format: v$version
+  update_changelog_on_bump: true
+  version_provider: scm
+  version_scheme: semver

.github/CODEOWNERS

@@ -1,8 +1,8 @@
-/.github/ @Splinter3D/Admins
-/scripts/ @Splinter3D/Admins
-/.clang-format @Splinter3D/Admins
-/.cz.toml @Splinter3D/Admins
-/.gitattributes @Splinter3D/Admins
-/.gitignore @Splinter3D/Admins
-/.pre-commit-config.yaml @Splinter3D/Admins
-/LICENSE @Splinter3D/Admins
+/.github/ @Splinter3D/Admins @Splinter3D/Maintainers
+/scripts/ @Splinter3D/Admins @Splinter3D/Maintainers
+/.clang-format @Splinter3D/Admins @Splinter3D/Maintainers
+/.cz.toml @Splinter3D/Admins @Splinter3D/Maintainers
+/.gitattributes @Splinter3D/Admins @Splinter3D/Maintainers
+/.gitignore @Splinter3D/Admins @Splinter3D/Maintainers
+/.pre-commit-config.yaml @Splinter3D/Admins @Splinter3D/Maintainers
+/LICENSE @Splinter3D/Admins @Splinter3D/Maintainers

.github/README.md

@@ -1 +1,94 @@
-# TODO: README
+# StyleCheck
+
+`StyleCheck` provides the `splinter3d_style` CLI and a published `pre-commit` hook.
+
+## Local Development
+
+Use Poetry for local development so the CLI, test dependencies, and release tooling stay aligned with the project metadata.
+
+```bash
+poetry install
+poetry run splinter3d_style
+poetry run pytest
+```
+
+If you need to enter the virtual environment directly:
+
+```bash
+poetry shell
+splinter3d_style
+pytest
+```
+
+## Build And Test Locally
+
+Build the distribution files locally before creating a release:
+
+```bash
+poetry run python -m build
+ls dist/
+```
+
+Test the built package rather than the source tree:
+
+```bash
+pipx install ./dist/splinter3d_style-X.Y.Z-py3-none-any.whl
+splinter3d_style
+pipx uninstall splinter3d_style
+```
+
+You can also validate the source distribution or wheel with a throwaway virtualenv:
+
+```bash
+python3 -m venv .venv-build-test
+. .venv-build-test/bin/activate
+pip install ./dist/splinter3d_style-X.Y.Z-py3-none-any.whl
+splinter3d_style
+deactivate
+```
+
+`X.Y.Z` is a placeholder. Use the actual filename created in `dist/`, or install the first built wheel directly:
+
+```bash
+pipx install "$(ls dist/*.whl | head -n 1)"
+```
+
+## Install From A Release
+
+Install a published release artifact with `pipx`:
+
+```bash
+pipx install https://github.com/<owner>/StyleCheck/releases/download/vX.Y.Z/splinter3d_style-X.Y.Z-py3-none-any.whl
+splinter3d_style
+```
+
+## Use With pre-commit
+
+Add this repository and a release tag to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/<owner>/StyleCheck
+    rev: vX.Y.Z
+    hooks:
+      - id: splinter3d-style
+```
+
+Then install and run:
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+## Release
+
+Releases are driven by pull requests and tags created by GitHub Actions:
+
+- Pull requests into `main` are only valid when they come from `dev` or `hotfix/*`.
+- When a pull request is merged into `dev`, CI creates a `vX.Y.Z-rc.N` tag.
+- When a pull request is merged into `main`, CI creates a `vX.Y.Z` tag.
+- Tag creation uses Commitizen to determine the next base version and defaults to `0.1.0` when no stable tag exists.
+- Every pushed release tag triggers the packaging workflow, which builds the distribution files and attaches them to a GitHub release.
+
+Protected GitHub environments can be applied to the `release-rc` and `release` jobs to gate prerelease and production publication independently.

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

.github/workflows/main-pr-policy.yml

@@ -0,0 +1,50 @@
+name: main-pr-policy
+
+on:
+  pull_request_target:
+    branches:
+      - main
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - edited
+      - ready_for_review
+
+jobs:
+  enforce-source-branch:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Close invalid pull request
+        run: |
+          head_ref="${{ github.head_ref }}"
+          pr_number="${{ github.event.pull_request.number }}"
+          repo="${{ github.repository }}"
+
+          if [[ "$head_ref" == "dev" || "$head_ref" =~ ^hotfix/ ]]; then
+            exit 0
+          fi
+
+          body='{"body":"Closing this PR automatically: pull requests into `main` must come from `dev` or `hotfix/*`."}'
+          state='{"state":"closed"}'
+
+          curl --fail-with-body \
+            --request POST \
+            --url "https://api.github.com/repos/${repo}/issues/${pr_number}/comments" \
+            --header "Authorization: Bearer ${GITHUB_TOKEN}" \
+            --header "Accept: application/vnd.github+json" \
+            --header "X-GitHub-Api-Version: 2022-11-28" \
+            --data "$body"
+
+          curl --fail-with-body \
+            --request PATCH \
+            --url "https://api.github.com/repos/${repo}/pulls/${pr_number}" \
+            --header "Authorization: Bearer ${GITHUB_TOKEN}" \
+            --header "Accept: application/vnd.github+json" \
+            --header "X-GitHub-Api-Version: 2022-11-28" \
+            --data "$state"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+  publish-prerelease:
+    if: contains(github.ref_name, '-rc.')
+    runs-on: ubuntu-latest
+    environment:
+      name: release-rc
+    needs: build
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - name: Create GitHub prerelease
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+          prerelease: true
+
+  publish-release:
+    if: ${{ !contains(github.ref_name, '-rc.') }}
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: release
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true