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 .codingstandardrc
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
source = "https://github.com/wesley-dean/coding_standards.git"
version = "coding_standards@v2.1.0"
sha256 = "ee04401441a3206d5cdc2bdc2e6d5130ff278ddc1ecd641f1c01843aa0666020"
version = "coding_standards@v3.2.0"
sha256 = "f4e09cc804b254c79d1139a7413f2ec5311c05e44deca93965e36b9e85ae51c8"
destination = "doc/standards"
8 changes: 4 additions & 4 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ updates:
prefix-development: chore
include: scope
groups:
minor-and-patch:
# Group eligible routine major/minor/patch versions, excluding security updates.
actions-version-updates:
applies-to: version-updates
update-types:
- "minor"
- "patch"
patterns:
- "*"
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ and focused fixtures.

## Shared Coding Standards

This repository adopts the complete pinned `coding_standards@v2.1.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization.
This repository adopts the complete pinned `coding_standards@v3.2.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization.

Authoritative shared documentation standards used here:

Expand Down
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -261,10 +261,14 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and

## Shared Coding Standards

This repository adopts the complete pinned `coding_standards@v2.1.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization.
This repository adopts the complete pinned `coding_standards@v3.2.0` snapshot under `doc/standards/`; `.codingstandardrc` records its verified release digest. Applicable imported standards are governing requirements unless an accepted local ADR or explicit policy refines them. Presence does not imply applicability, examples remain illustrative, imported standards are not edited locally, and upgrades are reviewed repository changes rather than automatic synchronization.

Authoritative shared documentation standards used here:

- Python: `doc/standards/python/documentation-standard.md`
- AWK: `doc/standards/awk/documentation-standard.md`


## Dependabot Maintenance

Routine GitHub Actions dependency version updates remain weekly with a seven-day cooldown. Eligible major, minor, and patch versions can be grouped under `actions-version-updates`; security updates remain independent. Groups containing a major upgrade require targeted manual review and are excluded from the existing non-major-only auto-merge path. Existing Dependabot PRs are not presumed superseded. See [ADR-013](doc/adr/ADR-013-consolidate-github-actions-dependabot-maintenance.md).
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# ADR-013: Consolidate GitHub Actions Dependabot Version Updates

Date: 2026-11-12

## Status

Accepted

## Decision

Keep the repository's weekly GitHub Actions Dependabot version-update
schedule, seven-day cooldown, and existing commit-message convention.
Replace `minor-and-patch` with a single `actions-version-updates` group
using `applies-to: version-updates` and `patterns: ["*"]`, without
`update-types`. Eligible major, minor, and patch routine updates may be
grouped together. Security updates remain separate from scheduled version
updates and must not be delayed by the cooldown.

Retain the existing `dependabot/fetch-metadata` guard excluding
`version-update:semver-major` from automatic merging. A group
containing a major upgrade must receive targeted manual review of its
highest-risk dependency and all material compatibility changes.

## Context, Constraints, and Assumptions

Previously, the minor/patch-only group allowed major GitHub Actions
versions to create additional routine PRs. The adopted
`coding_standards@v3.2.0` release recommends a balanced weekly
per-ecosystem group with a seven-day cooldown to reduce review volume,
without asserting a fixed number of PRs.

The maintained Python documentation translator is an AWK filter with
precisely governed recognition and preservation of Python source,
structured fields, Doxygen integration, supported AWK portability,
and three validated release artifact flavors. Accepted ADRs 001-012
remain authoritative. GitHub Actions dependency changes can affect
those testing and release-trust boundaries without changing source.

The only configured Dependabot ecosystem is GitHub Actions. The
auto-merge condition, required-check identities, token permissions,
and release-authority boundaries must remain unchanged. Effective
GitHub CODEOWNERS enforcement, branch rules, and Dependabot security
update settings require separate verification: repository YAML
does not establish those controls.

## Alternatives Considered

1. Keep minor/patch-only grouping. Rejected as the default because
major versions would continue generating separate routine PRs
without inherently stronger review evidence.
2. Group major/minor/patch versions per ecosystem. Chosen to reduce
routine review fragmentation, with major-containing groups
excluded from the non-major-only auto-merge path.
3. Move to monthly updates or extend the cooldown. Rejected because
delaying routine visibility has not been justified by maintenance
evidence or compatibility needs.
4. Auto-merge groups containing major updates. Rejected because
breaking changes and altered Action privileges may affect tests,
documentation, release validation, and published artifacts.
5. Close existing Dependabot PRs immediately. Rejected because a
changed configuration does not prove their dependencies have
been replaced or validated.

## Consequences, Risks, and Verification

Routine version-update PR count may decline, but resolver conflicts,
incompatible versions, or multiple update classes can still produce
separate PRs. Grouped failures may be harder to isolate. A risky or
incompatible dependency may justify a narrowly governed grouping
exception, without ignoring its updates entirely.

Each grouped PR requires review of each dependency's release notes,
permissions, migration impact, and test/release-path evidence.
Major-containing groups must not enter the existing automatic-merge
route. Existing Dependabot PR #18 stays open unless later updates
demonstrably supersede it with sufficient checks.

Observe actual post-merge Dependabot runs and compare PR counts and
review effort. Verify security-alert and security-update settings
and effective review protections independently. No change to
Python translation, AWK source, test fixtures, compatibility floor,
Doxygen representation, or release artifact contract is authorized.

## Related Decisions

ADR-012 governs the frozen released standards snapshot and its
provenance; ADR-011 governs three generated artifact flavors;
ADRs 001-010 govern parsing, representation, integration, and
testing. This ADR supplements, but does not supersede, them.
13 changes: 12 additions & 1 deletion doc/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ offline artifact-generation primitive. See

**Status:** Accepted

The repository adopts the complete verified `coding_standards@v2.1.0` snapshot
The repository currently pins the complete verified `coding_standards@v3.2.0` snapshot
beneath `doc/standards/`, with exact release provenance recorded in
`.codingstandardrc`. Applicable imported standards govern where relevant while
accepted repository-specific ADRs and explicit local policy retain precedence for
Expand All @@ -140,3 +140,14 @@ historical ADR text remains unchanged. Future standards upgrades replace the
complete snapshot through normal review rather than local edits or automatic
synchronization. See
[ADR-012](adr/ADR-012-adopt-shared-coding-standards.md).

## ADR-013: Consolidate GitHub Actions Dependabot Version Updates

Routine GitHub Actions version updates retain their weekly schedule and seven-day
cooldown, but a wildcard group now permits eligible major, minor, and patch
upgrades to appear together. Dependabot security updates remain separate; a
major-containing group requires targeted manual review and remains outside the
existing non-major auto-merge path. No Python filter behavior, source parsing,
release artifact, or documentation compatibility contract is changed.

See [ADR-013](adr/ADR-013-consolidate-github-actions-dependabot-maintenance.md).
24 changes: 24 additions & 0 deletions doc/standards/examples/repository/github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Non-normative GitHub Actions example. Copy to .github/dependabot.yml
# through a separate reviewed repository change. Add other ecosystems
# deliberately after reviewing their manifests and CI evidence.
#
# Source: standards/general/dependabot-maintenance-standard.md
---
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
commit-message:
prefix: fix
include: scope
groups:
# Routine major, minor, and patch releases in one version-update group.
# Security updates use independent repository settings/triggering.
actions-version-updates:
applies-to: version-updates
patterns:
- "*"
16 changes: 9 additions & 7 deletions doc/standards/examples/repository/github/pull-request.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,11 @@ merely because the build step completed successfully.

## Verification

- [x] Relevant automated tests pass.
- [x] Generated or distributed artifacts were verified where applicable.
- [x] Documentation affected by this change was updated.
- [x] Governing ADRs and standards affected by this change were reviewed.
- [x] Local archive structure and checksum verification passed.
- [x] CI is still pending; no CI pass is claimed yet.
- [x] Generated archive locally verified against the documented contract.
- [x] Documentation affected by this change updated.
- [x] Governing ADRs and standards affected by this change reviewed.

## Known Limitations and Follow-Up

Expand All @@ -46,7 +47,8 @@ artifact signing; that remains separate scope.
- [x] The pull request title reflects the highest semantic significance of the
complete change.
- [x] The diff remains within the declared scope.
- [x] Required verification has been completed to the extent available.
- [x] Available author-side verification completed and honestly reported.
- [x] Material assumptions, limitations, and risks are visible.
- [x] The pull request is ready for normal review and may be merged once repository
checks and review requirements are satisfied.
- [x] Final planned commits pushed; no further implementation is expected.
- [x] PR marked Ready while CI remains pending.
- [x] Auto-merge armed; protected CI and human review gate merge.
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
{
"name": "CI check gate (reviewed example)",
"target": "branch",
"enforcement": "active",
"bypass_actors": [],
"conditions": {
"ref_name": {
"include": [
"refs/heads/main"
],
"exclude": []
}
},
"rules": [
{
"type": "required_status_checks",
"parameters": {
"strict_required_status_checks_policy": true,
"required_status_checks": [
{
"context": "test-gate"
}
]
}
}
]
}
34 changes: 34 additions & 0 deletions doc/standards/examples/repository/github/workflows/ci-gate.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
# Non-normative reference example; copy through a reviewed local change.
# PR-head ref below is suitable for branch-push test checks. Review mixed
# push/PR event and fork semantics before using as an authoritative gate.
name: CI check gate

# yamllint disable-line rule:truthy
on:
pull_request:
types: [opened, synchronize, reopened]

permissions:
contents: read
checks: read

jobs:
aggregate:
name: test-gate
runs-on: ubuntu-24.04
timeout-minutes: 120
permissions:
contents: read
checks: read
steps:
- name: Wait for observed standardized CI checks
uses: matiasalbarello/wait-on-check-action-ts@8087812521cdb59ebc7751984b31b17209b30eeb # v1.2.0
with:
ref: ${{ github.event.pull_request.head.sha }}
repo-token: ${{ github.token }}
check-regexp: '^(test|e2e|end-to-end|integration|lint|security|build|compat)(-.+)?$'
running-workflow-name: test-gate
allowed-conclusions: success,skipped,cancelled
fail-on-no-checks: 'false'
wait-interval: '10'
Loading