Skip to content

Commit 29cd75a

Browse files
denisecasedenisecase
committed
update
1 parent ee916ac commit 29cd75a

7 files changed

Lines changed: 223 additions & 67 deletions

File tree

‎.editorconfig‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
# NOTE: Sections are ordered by editorial importance, not strict alphabetical order.
66
# EditorConfig is documented at https://editorconfig.org
77

8-
[*.{editorconfig}]
98
root = true
109

1110
# === Global defaults (always apply) ===

‎.github/workflows/ci-hygiene.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# ============================================================
2+
# .github/workflows/ci-hygiene.yml (Continuous Integration)
3+
# ============================================================
4+
# VARIANT: hygiene-ci
5+
# SOURCE: https://github.com/denisecase/templates
6+
#
7+
# WHY-FILE: Minimal checks for repositories where hygiene is the primary gate.
8+
# REQ: Any check that can be run locally MUST be available locally via pre-commit.
9+
# REQ: CI MUST NOT introduce arbitrary rules that are not reproducible locally.
10+
# OBS: CI does not introduce additional style rules beyond repo configuration.
11+
12+
name: CI Hygiene
13+
14+
# WHY: Validate repo contents on pushes to main branch and pull requests.
15+
16+
on:
17+
push:
18+
branches: [main] # WHY: Run when pushing to main branch.
19+
pull_request:
20+
branches: [main] # WHY: Run on pull requests targeting main branch.
21+
workflow_dispatch: # WHY: Allow manual triggering from Actions tab.
22+
23+
permissions: # WHY: Use least privileges required.
24+
contents: read
25+
26+
env:
27+
PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
28+
PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
29+
30+
jobs:
31+
ci:
32+
name: Repository checks (pre-commit)
33+
runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
34+
timeout-minutes: 10 # WHY: Prevent hanging jobs. If over, it is likely stuck.
35+
36+
steps:
37+
# ============================================================
38+
# ASSEMBLE: Get code and set up environment
39+
# ============================================================
40+
41+
- name: 1) Checkout repository code
42+
# WHY: Needed to access files for checks.
43+
uses: actions/checkout@v6
44+
45+
- name: 2) Run pre-commit (all files)
46+
# WHY: Single source of truth for locally runnable quality gates.
47+
# OBS: Fails if hooks would modify files; does not commit changes.
48+
id: precommit # WHY: Identify step for conditional follow-up.
49+
uses: pre-commit/action@v3.0.1
50+
with:
51+
extra_args: --all-files
52+
53+
- name: 2f) If pre-commit failed, run it locally
54+
if: failure()
55+
run: |
56+
echo "## Pre-commit failed" >> "$GITHUB_STEP_SUMMARY"
57+
echo "Please run pre-commit locally and commit the resulting changes." >> "$GITHUB_STEP_SUMMARY"

‎.github/workflows/ci.yml‎

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎.pre-commit-config.yaml‎

Lines changed: 67 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,100 @@
1-
# REQ.PROJECT: This repository SHOULD include a .pre-commit-config.yaml when quality gates are required.# REQ: Any check that can be run locally MUST be available here.# WHY: Provide fast, consistent local checks aligned with upstream quality gates.# WHY: Keep local checks compatible with repository-wide formatting rules.# OBS: Formatting baselines are defined in# .editorconfig (whitespace/indentation) and# .gitattributes (EOL normalization).# OBS: These hooks do not override .editorconfig or .gitattributes;# they only prevent common diff noise and validate repository metadata.# ALT: Checks that are inherently non-local are handled upstream.# CUSTOM: Keep the hook set minimal and non-destructive for normative Markdown specs.## OPTIONAL LOCAL USAGE (no repo venv required):# Install uv (once, user-level).# uv self update# uvx pre-commit install# uvx pre-commit run --all-files## OBS: If a hook reports "files were modified", re-run last command to confirm a clean pass.## NOTE: pre-commit is optional.# Repositories do not require Python, uv, or pre-commit to clone or commit.exclude: | (?x)^( \.DS_Store| \.ipynb_checkpoints/| \.mypy_cache/| \.pytest_cache/| \.ruff_cache/| \.tox/| \.venv/| build/| dist/| node_modules/| site/ )repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 # OBS: v6 current as of Dec 30 2025 hooks: - id: check-added-large-files # OBS: prevent large binary files - id: trailing-whitespace # OBS: clean trailing whitespace per .editorconfig - id: end-of-file-fixer # OBS: ensure files end with a newline per .gitattributes - id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts # WHY: Workflow files may intentionally include marker-like strings (e.g., >>>>). exclude: ^\.github/workflows/.*\.(yml|yaml)$ - id: check-yaml # OBS: validate YAML syntax files: \.(yml|yaml)$ - repo: https://github.com/adrienverge/yamllint rev: v1.37.1 # OBS: pinned for reproducibility hooks: - id: yamllint # OBS: validate YAML structure and policy (no line-length enforcement) args: [-c, .yamllint.yml] files: \.(yml|yaml)$ - repo: https://github.com/rhysd/actionlint rev: v1.7.10 # OBS: v1.7.10 current as of Dec 30 2025 hooks: - id: actionlint # OBS: validate GitHub Actions workflow syntax files: ^\.github/workflows/.*\.(yml|yaml)$# REQ.PROJECT: This repository SHOULD include a .pre-commit-config.yaml when quality gates are required.
2-
# REQ: Any check that can be run locally MUST be available here.
3-
# WHY: Provide fast, consistent local checks aligned with upstream quality gates.
4-
# WHY: Keep local checks compatible with repository-wide formatting rules.
5-
# OBS: Formatting baselines are defined in
6-
# .editorconfig (whitespace/indentation) and
7-
# .gitattributes (EOL normalization).
8-
# OBS: These hooks do not override .editorconfig or .gitattributes;
9-
# they only prevent common diff noise and validate repository metadata.
10-
# ALT: Checks that are inherently non-local are handled upstream.
11-
# CUSTOM: Keep the hook set minimal and non-destructive for normative Markdown specs.
1+
# ============================================================
2+
# .pre-commit-config.yaml (Markdown Hygiene)
3+
# ============================================================
4+
# VARIANT: markdown-hygiene
5+
# SOURCE: https://github.com/denisecase/templates
6+
#
7+
# REQ: Documentation-only repos MAY include a .pre-commit-config.yaml for repo hygiene (optional).
8+
# WHY: Keep Markdown diffs clean across OSes and prevent common documentation commit errors.
9+
#
10+
# OBS: These hooks use and do NOT override:
11+
# - .editorconfig (whitespace / indentation)
12+
# - .gitattributes (EOL normalization)
1213
#
1314
# OPTIONAL LOCAL USAGE (no repo venv required):
1415
# Install uv (once, user-level).
1516
# uv self update
1617
# uvx pre-commit install
17-
# uvx pre-commit run --all-files
18-
#
19-
# OBS: If a hook reports "files were modified", re-run last command to confirm a clean pass.
18+
# uvx pre-commit run --all-files (just once, to check all files)
19+
# Subsequent commits will AUTOMATICALLY run pre-commit hooks after git add
20+
# and before git commit.
2021
#
2122
# NOTE: pre-commit is optional.
22-
# Repositories do not require Python, uv, or pre-commit to clone or commit.
23+
# Repositories do NOT require Python, uv, or pre-commit to clone or commit.
2324

2425
exclude: |
2526
(?x)^(
2627
\.DS_Store|
28+
\.coverage|
2729
\.ipynb_checkpoints/|
2830
\.mypy_cache/|
31+
\.nox/|
2932
\.pytest_cache/|
3033
\.ruff_cache/|
3134
\.tox/|
3235
\.venv/|
36+
.*\.(egg-info)/|
37+
.*\.log|
38+
__pycache__/|
39+
_minted.*/|
3340
build/|
41+
coverage\.xml|
3442
dist/|
43+
htmlcov/|
44+
lake-packages/|
3545
node_modules/|
46+
out/|
3647
site/
3748
)
3849
3950
repos:
51+
# === REPO: PRE-COMMIT HOOKS (cross-platform, zero config) ===
52+
#
53+
# These hooks prevent problems that show up later as:
54+
# - mysterious diffs
55+
# - broken builds on another OS
56+
4057
- repo: https://github.com/pre-commit/pre-commit-hooks
4158
rev: v6.0.0
4259
hooks:
43-
- id: check-added-large-files # OBS: prevent large binary files
44-
- id: trailing-whitespace # OBS: clean trailing whitespace per .editorconfig
45-
- id: end-of-file-fixer # OBS: ensure files end with a newline per .gitattributes
60+
# === PRE-COMMIT: NORMALIZE FILE FORMATTING ===
4661

47-
- id: mixed-line-ending # OBS: normalize line endings before linters run
48-
# WHY: yamllint enforces LF; Windows working copies may be CRLF.
49-
args: [--fix=lf]
62+
- id: trailing-whitespace
63+
name: A1) Clean trailing whitespace (per .editorconfig)
64+
args: [--markdown-linebreak-ext=md] # Preserves markdown double-space line breaks
5065

51-
- id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts
66+
- id: end-of-file-fixer
67+
name: A2) End files with a newline (per .gitattributes)
5268

53-
- id: check-yaml # OBS: validate YAML syntax
54-
files: \.(yml|yaml)$
69+
- id: mixed-line-ending
70+
name: A3) Normalize line endings to LF before linters
71+
args: [--fix=lf] # OBS: Windows working copies may be CRLF.
5572

56-
- repo: https://github.com/adrienverge/yamllint
57-
rev: v1.37.1
58-
hooks:
59-
- id: yamllint # OBS: validate YAML structure and policy (no line-length enforcement)
60-
args: [-c, .yamllint.yml]
73+
# === PRE-COMMIT: CHECK DATA FILE FORMATS ===
74+
75+
- id: check-json
76+
name: B1) Validate JSON syntax
77+
78+
- id: check-toml
79+
name: B2) Validate TOML syntax
80+
81+
- id: check-yaml
82+
name: B3) Validate YAML syntax
6183
files: \.(yml|yaml)$
84+
exclude: ^mkdocs\.ya?ml$ # OBS: mkdocs.yaml may include non-standard tags.
6285

63-
- repo: https://github.com/rhysd/actionlint
64-
rev: v1.7.10
65-
hooks:
66-
- id: actionlint # OBS: validate GitHub Actions workflow syntax
67-
files: ^\.github/workflows/.*\.(yml|yaml)$
86+
# === PRE-COMMIT:CHECK FOR COMMON PROBLEMS ===
87+
88+
- id: check-added-large-files
89+
name: C1) Prevent accidental commits of large binaries
90+
args: [--maxkb=500]
91+
92+
- id: check-merge-conflict
93+
name: C2) Prevent committing merge conflicts
94+
95+
- id: check-case-conflict
96+
name: C3) Check for filename case conflicts
97+
98+
# === GLOBAL SETTINGS ===
99+
# ALT: Set fail_fast to true to stop at first failure.
100+
fail_fast: false # Run all hooks even if one fails

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.12

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,35 @@
66

77

88
> GitHub profile repo for the structural-explainability organization on GitHub.
9+
10+
11+
## Developer
12+
13+
Initialize:
14+
15+
```shell
16+
uv self update
17+
uvx pre-commit install
18+
uvx pre-commit run --all-files
19+
```
20+
21+
When starting a new session always git pull:
22+
23+
```shell
24+
git pull
25+
```
26+
27+
Save progress:
28+
29+
```shell
30+
git add -A
31+
# If pre-commit makes changes, re-run `git add -A` before committing.
32+
git commit -m "update"
33+
git push -u origin main
34+
```
35+
36+
## Resources
37+
38+
See `.github\workflows` for available GitHub actions.
39+
40+
See `.devcontainer` for alternatives to local development.

‎SE_MANIFEST.toml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# ============================================================
2+
# .github/SE_MANIFEST.toml (Repository Intent, Scope, and Role)
3+
# ============================================================
4+
5+
schema = "se-manifest-1"
6+
schema_url = "https://github.com/structural-explainability/spec-se/blob/main/manifests/se-manifest-1.md"
7+
8+
[meta]
9+
# Non-normative contextual information
10+
framework = "Structural Explainability"
11+
framework_url = "https://github.com/structural-explainability"
12+
framework_note = "Provides definitions and conventions for SE_MANIFEST semantics."
13+
description = "Declarative claim of repository intent, scope, and role."
14+
purpose = "To make explicit the boundaries, responsibilities, and expectations of this repository relative to others."
15+
16+
[repo]
17+
name = ".github"
18+
org = "structural-explainability"
19+
kind = "governance"
20+
status = "public"
21+
since = "2025"
22+
summary = "Organization-wide community health files, contribution workflows, and governance scaffolding for Structural Explainability."
23+
24+
[layer]
25+
space = "SE"
26+
role = "governance"
27+
28+
[depends]
29+
required = []
30+
optional = []
31+
32+
[provides]
33+
artifacts = [
34+
"README.md",
35+
"CODE_OF_CONDUCT.md",
36+
"CONTRIBUTING.md",
37+
"SECURITY.md",
38+
".github/",
39+
".github/workflows/",
40+
"SE_MANIFEST.toml"
41+
]
42+
43+
[scope]
44+
includes = [
45+
"organization-level contribution guidance",
46+
"issue and pull request templates",
47+
"repository and community health defaults",
48+
"workflow templates and CI policy scaffolding",
49+
"non-normative operational guidance for contributors"
50+
]
51+
excludes = [
52+
"normative specification definitions",
53+
"formal constraints or invariants",
54+
"conformance requirements",
55+
"implementation logic",
56+
"domain semantics",
57+
"interpretive or evaluative claims"
58+
]
59+
60+
[citation]
61+
cff = "CITATION.cff"
62+
preferred = "repo"
63+
bib_hint = "case2025-se-github"
64+
65+
[traceability]
66+
identifier_map = "none"

0 commit comments

Comments
 (0)