Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/scripts/check_lint.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/check_package.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/check_security.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/check_spelling.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/check_tests.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/check_types.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/qa.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
"""Local QA orchestrator. Discovers and runs all check_*.py scripts.

Usage:
Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/setup.ps1
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
$ErrorActionPreference = 'Stop'

$ScriptDir = Split-Path -Parent $PSCommandPath
Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/setup.sh
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/self-update.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ jobs:
if [ -n "${{ inputs.tag }}" ]; then
echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
else
tag=$(gh release view --repo nwarila/python-template --json tagName --jq '.tagName')
tag=$(gh release view --repo NWarila/python-template --json tagName --jq '.tagName')
echo "tag=$tag" >> "$GITHUB_OUTPUT"
fi

Expand Down Expand Up @@ -66,7 +66,7 @@ jobs:
run: |
tag="${{ steps.tag.outputs.tag }}"
git clone --depth 1 --branch "$tag" \
https://github.com/nwarila/python-template.git /tmp/template
https://github.com/NWarila/python-template.git /tmp/template

- name: Sync files from manifest
if: steps.skip.outputs.skip == 'false'
Expand Down Expand Up @@ -99,7 +99,7 @@ jobs:
--body "$(cat <<EOF
## Template Sync: ${tag}

Pulls template-managed files from [python-template@${tag}](https://github.com/nwarila/python-template/releases/tag/${tag}).
Pulls template-managed files from [python-template@${tag}](https://github.com/NWarila/python-template/releases/tag/${tag}).

Review the changes and merge when ready.

Expand Down
4 changes: 2 additions & 2 deletions .markdownlint-cli2.jsonc
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Managed by nwarila/python-template — do not edit manually.
// Source: https://github.com/nwarila/python-template
// Managed by NWarila/python-template — do not edit manually.
// Source: https://github.com/NWarila/python-template
{
"config": {
"MD013": false,
Expand Down
22 changes: 11 additions & 11 deletions PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Mission

Create `nwarila/python-template` and `nwarila/.github` as the two-layer
Create `NWarila/python-template` and `NWarila/.github` as the two-layer
standard for every Python repository in the organization.

- `.github` owns organization-wide governance, repository policy, workflow
Expand Down Expand Up @@ -103,7 +103,7 @@ Why this is the better fit:
### Repository shape

```text
nwarila/python-template
NWarila/python-template
├── .github/
│ ├── actions/
│ │ └── setup-python/
Expand Down Expand Up @@ -621,7 +621,7 @@ Exit criteria:
breaking changes
- [ ] Add workflow templates in `.github` that call the shared reusable
workflow, including the required `.properties.json` metadata files
- [ ] Pilot the standard in `nwarila/resume`
- [ ] Pilot the standard in `NWarila/resume`
- [ ] Pilot the standard in at least one additional Python repo with a
different profile
- [ ] Cut `v1.0.0` and maintain the floating `v1` tag
Expand Down Expand Up @@ -787,13 +787,13 @@ path was taken; they run against the activated venv regardless.
### Sync mechanism

Sync is **pull-based**. Each downstream repo owns a `template-sync.yml`
workflow that pulls released files from `nwarila/python-template`. The template
workflow that pulls released files from `NWarila/python-template`. The template
publishes releases; downstream repos pull when ready. No cross-repo credentials,
no push permissions, no coupling.

Each downstream repo's sync workflow:

1. Checks for the latest release on `nwarila/python-template` (or accepts a
1. Checks for the latest release on `NWarila/python-template` (or accepts a
manual tag input)
2. Clones the template at the release tag
3. Runs `scripts/sync.py` from the template clone, which reads
Expand All @@ -803,7 +803,7 @@ Each downstream repo's sync workflow:
4. Opens a PR via `gh pr create` using the repo's own `GITHUB_TOKEN`

`self-update.yml` supports `workflow_call`, so downstream repos call it as a
reusable workflow via `uses: nwarila/python-template/.github/workflows/self-update.yml@v1`
reusable workflow via `uses: NWarila/python-template/.github/workflows/self-update.yml@v1`
from a thin wrapper with their own schedule trigger.

**`sync-manifest.json` schema:**
Expand All @@ -823,8 +823,8 @@ from a thin wrapper with their own schedule trigger.
Synced files carry a header comment identifying their source:

```python
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
# Version: v1.2.3
```

Expand All @@ -836,7 +836,7 @@ top of the file in the same format.
The org-standard `reference/settings.json` includes only universal settings:

```jsonc
// Managed by nwarila/python-template — do not edit manually.
// Managed by NWarila/python-template — do not edit manually.
{
// Python formatting
"[python]": {
Expand Down Expand Up @@ -984,7 +984,7 @@ conflicting — the template dogfoods what the org requires.
pattern traverses parent directories until it finds `pyproject.toml`,
working from any depth. Applied to `qa.py`, `setup.sh`, and `setup.ps1`.

## Pilot Migration: `nwarila/resume`
## Pilot Migration: `NWarila/resume`

The resume repo is the first adopter and the original motivation for this
template. Here is the concrete migration path:
Expand Down Expand Up @@ -1016,7 +1016,7 @@ template. Here is the concrete migration path:
```yaml
jobs:
python-qa:
uses: nwarila/python-template/.github/workflows/python-qa.yml@v1
uses: NWarila/python-template/.github/workflows/python-qa.yml@v1
with:
python-min: "3.11"
python-max: "3.12"
Expand Down
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
# python-template

[![CI](https://github.com/nwarila/python-template/actions/workflows/template-ci.yml/badge.svg)](https://github.com/nwarila/python-template/actions/workflows/template-ci.yml)
[![Coverage](https://codecov.io/gh/nwarila/python-template/graph/badge.svg)](https://codecov.io/gh/nwarila/python-template)
[![CI](https://github.com/NWarila/python-template/actions/workflows/template-ci.yml/badge.svg)](https://github.com/NWarila/python-template/actions/workflows/template-ci.yml)
[![Coverage](https://codecov.io/gh/NWarila/python-template/graph/badge.svg)](https://codecov.io/gh/NWarila/python-template)
[![Python](https://img.shields.io/badge/python-%E2%89%A53.11-3776ab?logo=python&logoColor=white)](https://www.python.org)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)](https://github.com/nwarila/python-template)
[![License](https://img.shields.io/github/license/nwarila/python-template)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)](https://github.com/NWarila/python-template)
[![License](https://img.shields.io/github/license/NWarila/python-template)](LICENSE)

Reusable Python quality-gate scripts, a reusable CI workflow, and reference configurations that define a consistent developer experience across all Python repositories in the **nwarila** GitHub organization.
Reusable Python quality-gate scripts, a reusable CI workflow, and reference configurations that define a consistent developer experience across all Python repositories in the **NWarila** GitHub account.

This repo is the Python-specific layer of a two-layer governance model. For org-wide community health files, issue templates, and baseline CI, see [nwarila/.github](https://github.com/nwarila/.github).
This repo is the Python-specific layer of a two-layer governance model. For org-wide community health files, issue templates, and baseline CI, see [NWarila/.github](https://github.com/NWarila/.github).

## Architecture

| Layer | Repo | Responsibility |
| --- | --- | --- |
| Org governance | `nwarila/.github` | Community health files, issue and PR templates, baseline CI, workflow templates |
| Python QA | `nwarila/python-template` | Check scripts, reusable workflow, setup action, sync manifest, reference configs |
| Org governance | `NWarila/.github` | Community health files, issue and PR templates, baseline CI, workflow templates |
| Python QA | `NWarila/python-template` | Check scripts, reusable workflow, setup action, sync manifest, reference configs |

Downstream Python repos consume both layers through different mechanisms. The `.github` repo provides defaults through GitHub's built-in inheritance; this repo ships Python-specific scripts and configs through tagged releases that downstream repos pull on their own schedule.

Expand Down Expand Up @@ -92,7 +92,7 @@ Downstream repos copy `reference/repo-ci.yml` into `.github/workflows/ci.yml` an
```yaml
jobs:
python-qa:
uses: nwarila/python-template/.github/workflows/python-qa.yml@v1
uses: NWarila/python-template/.github/workflows/python-qa.yml@v1
```

The reusable workflow runs each quality gate as a separate job and publishes a single stable `ci-passed` aggregator result.
Expand Down Expand Up @@ -129,7 +129,7 @@ permissions:
pull-requests: write
jobs:
sync:
uses: nwarila/python-template/.github/workflows/self-update.yml@v1
uses: NWarila/python-template/.github/workflows/self-update.yml@v1
```

The workflow checks for new releases, reads `sync-manifest.json` to know which files to copy and where, and opens a PR using the repo's own `GITHUB_TOKEN`. No PAT required.
Expand All @@ -151,9 +151,9 @@ Each repo controls its own update cadence — the template publishes releases, c

## Git Hygiene Standard

The org-standard `.gitignore` uses an explicit allowlist model and starts with `**`, matching the control-plane style used in `nwarila/.github`. Repos intentionally allow tracked roots and keep generated artifacts ignored even inside allowed paths.
The org-standard `.gitignore` uses an explicit allowlist model and starts with `**`, matching the control-plane style used in `NWarila/.github`. Repos intentionally allow tracked roots and keep generated artifacts ignored even inside allowed paths.

The org-standard `.gitattributes` is comment-rich and standardized, defining LF normalization and markdown diff behavior in a format aligned with `nwarila/.github`.
The org-standard `.gitattributes` is comment-rich and standardized, defining LF normalization and markdown diff behavior in a format aligned with `NWarila/.github`.

## Quick Start For A New Repo

Expand Down
4 changes: 2 additions & 2 deletions reference/extensions.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Managed by nwarila/python-template — do not edit manually.
// Source: https://github.com/nwarila/python-template
// Managed by NWarila/python-template — do not edit manually.
// Source: https://github.com/NWarila/python-template
{
"recommendations": [
"charliermarsh.ruff",
Expand Down
4 changes: 2 additions & 2 deletions reference/markdownlint-cli2.jsonc
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Managed by nwarila/python-template — do not edit manually.
// Source: https://github.com/nwarila/python-template
// Managed by NWarila/python-template — do not edit manually.
// Source: https://github.com/NWarila/python-template
{
"config": {
"MD013": false,
Expand Down
4 changes: 2 additions & 2 deletions reference/pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
default_install_hook_types: [pre-commit, pre-push]

repos:
Expand Down
4 changes: 2 additions & 2 deletions reference/repo-ci.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Example CI workflow for a Python repo adopting nwarila/python-template.
# Example CI workflow for a Python repo adopting NWarila/python-template.
# Copy to .github/workflows/ci.yml and customize as needed.
# Also add a template-sync.yml workflow that calls self-update.yml via uses:
# to receive automatic script and config updates via pull request.
Expand All @@ -23,7 +23,7 @@ concurrency:

jobs:
python-qa:
uses: nwarila/python-template/.github/workflows/python-qa.yml@v1
uses: NWarila/python-template/.github/workflows/python-qa.yml@v1
with:
python-min: "3.11"
python-max: "3.12"
Expand Down
4 changes: 2 additions & 2 deletions reference/settings.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Managed by nwarila/python-template — do not edit manually.
// Source: https://github.com/nwarila/python-template
// Managed by NWarila/python-template — do not edit manually.
// Source: https://github.com/NWarila/python-template
{
// #region Template: Python -------------------------------------------------
"[python]": {
Expand Down
4 changes: 2 additions & 2 deletions reference/tasks.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Managed by nwarila/python-template — do not edit manually (template regions only).
// Source: https://github.com/nwarila/python-template
// Managed by NWarila/python-template — do not edit manually (template regions only).
// Source: https://github.com/NWarila/python-template
{
"version": "2.0.0",
"tasks": [
Expand Down
4 changes: 2 additions & 2 deletions scripts/check_lint.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions scripts/check_package.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions scripts/check_security.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions scripts/check_spelling.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions scripts/check_tests.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions scripts/check_types.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template

from __future__ import annotations

Expand Down
4 changes: 2 additions & 2 deletions scripts/qa.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
"""Local QA orchestrator. Discovers and runs all check_*.py scripts.

Usage:
Expand Down
4 changes: 2 additions & 2 deletions scripts/setup.ps1
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
$ErrorActionPreference = 'Stop'

$ScriptDir = Split-Path -Parent $PSCommandPath
Expand Down
4 changes: 2 additions & 2 deletions scripts/setup.sh
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
# Managed by nwarila/python-template — do not edit manually.
# Source: https://github.com/nwarila/python-template
# Managed by NWarila/python-template — do not edit manually.
# Source: https://github.com/NWarila/python-template
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
Expand Down
Loading