From 883810cd145b1993d71ef70e0b092d93a21bbc2f Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Thu, 1 Oct 2026 10:02:54 +0800 Subject: [PATCH] docs(workflow): move specs under docs and use major action tags Specs now live in docs/specs/, next to docs/plans/, so all design documents sit under docs/. Workflows reference actions by their latest major tag instead of a commit SHA, and CONTRIBUTING records that convention. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/ci.yml.example | 2 +- .github/workflows/review.yml | 6 +++--- AGENTS.md | 2 +- CHANGELOG.md | 3 ++- CONTRIBUTING.md | 6 ++++-- README.md | 4 ++-- docs/README.md | 2 +- {specs => docs/specs}/0000-template.md | 2 +- {specs => docs/specs}/README.md | 2 +- scripts/check-repository.sh | 2 +- 10 files changed, 17 insertions(+), 14 deletions(-) rename {specs => docs/specs}/0000-template.md (83%) rename {specs => docs/specs}/README.md (70%) diff --git a/.github/workflows/ci.yml.example b/.github/workflows/ci.yml.example index 82f1f7e..a26aa1a 100644 --- a/.github/workflows/ci.yml.example +++ b/.github/workflows/ci.yml.example @@ -10,6 +10,6 @@ jobs: name: test runs-on: ubuntu-latest steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7 # Replace with project-specific setup and validation commands. - run: echo "Configure CI for this project" diff --git a/.github/workflows/review.yml b/.github/workflows/review.yml index f6cbd0f..67108f4 100644 --- a/.github/workflows/review.yml +++ b/.github/workflows/review.yml @@ -11,7 +11,7 @@ jobs: name: repository checks runs-on: ubuntu-latest steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7 - run: ./scripts/check-repository.sh pr-title: @@ -19,7 +19,7 @@ jobs: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7 - run: ./scripts/check-pr-title.sh "$PR_TITLE" env: PR_TITLE: ${{ github.event.pull_request.title }} @@ -30,7 +30,7 @@ jobs: if: github.event_name == 'pull_request' && github.event.pull_request.user.type != 'Bot' runs-on: ubuntu-latest steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7 - run: printf '%s\n' "$PR_BODY" | ./scripts/check-pr-body.sh env: PR_BODY: ${{ github.event.pull_request.body }} diff --git a/AGENTS.md b/AGENTS.md index fe53436..87506f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,7 +72,7 @@ For non-trivial changes: - Keep `README.md` focused on orientation, quick start, and current user-facing behavior. - Use `CONTRIBUTING.md` for contribution workflow. -- Use `specs/` for active product behavior and `docs/plans/` for active technical decisions and detailed execution plans. Current-state documentation owns implemented behavior. +- Use `docs/specs/` for active product behavior and `docs/plans/` for active technical decisions and detailed execution plans. Current-state documentation owns implemented behavior. - Use `docs/` for durable current-state knowledge such as architecture, development guides, operational runbooks, references, and onboarding tutorials. - Update `CHANGELOG.md` for user-facing changes unless the change is docs-only or repository-only. - When behavior, configuration, commands, APIs, deployment, architecture, or operations change, update the relevant docs in the same PR/MR or explain why no docs changed. diff --git a/CHANGELOG.md b/CHANGELOG.md index c52a162..5890a96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,8 @@ ## Unreleased -- Workflows pin `actions/checkout` to the v7.0.1 commit SHA; downstream repositories take action bumps from this template instead of editing `review.yml` locally. +- Workflows use `actions/checkout@v7`; actions are referenced by their latest major version tag, not a commit SHA. Downstream repositories take action upgrades from this template instead of editing `review.yml` locally. +- Specs moved from `specs/` to `docs/specs/`, next to `docs/plans/`. - `configure-github-repository.sh` accepts `--approvals N` (use 0 for a single maintainer) and repeatable `--check NAME` for project CI jobs. - Removed trailing blank lines that failed `git diff --cached --check` in repositories copying the template files. - Plans now pair technical decisions with a detailed execution plan: preconditions, completion contract, ordered tasks with exit conditions, validation ledger, and rollback per batch. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c54cf4d..46048dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -92,7 +92,7 @@ Every change needs a requirement record. Use the smallest set of artifacts that | Technical refactor without changed user behavior | Detailed Plan with compatibility and acceptance conditions | | Narrow maintenance, tests, or documentation | Requirement and PR checklist; a separate Plan only when useful | -A Spec defines observable interactions, scope, failure behavior, and acceptance examples. Use stable scenario IDs and Given/When/Then where useful. Link scenarios to tests. A Spec does not prescribe components, interfaces, or execution order. Keep active Specs under [`specs/`](specs/). A small change may keep both sections in the PR description. Split only when each slice has an independently demonstrable outcome. +A Spec defines observable interactions, scope, failure behavior, and acceptance examples. Use stable scenario IDs and Given/When/Then where useful. Link scenarios to tests. A Spec does not prescribe components, interfaces, or execution order. Keep active Specs under [`docs/specs/`](docs/specs/). A small change may keep both sections in the PR description. Split only when each slice has an independently demonstrable outcome. A Plan records technical decisions and the detailed execution plan that implements them. Shared architecture, compatibility, security, and recovery decisions belong in a reviewed Plan. After implementation, move lasting constraints into current-state architecture or operations docs. This template does not keep an RFC directory. Removing a proposal does not mark unimplemented ideas as delivered. @@ -125,7 +125,7 @@ Keep each documentation surface focused: - Use `README.md` for orientation, quick start, and current user-facing behavior. - Use `CONTRIBUTING.md` for contribution workflow, review expectations, and repository policy. - Use `AGENTS.md` for AI-agent instructions. -- Use `specs/` for active product behavior and acceptance contracts. +- Use `docs/specs/` for active product behavior and acceptance contracts. - Use `docs/plans/` for active technical decisions and detailed execution plans. Migrate lasting decisions into current-state docs. - Use `docs/` for durable current-state knowledge: architecture, development guides, operational runbooks, references, and onboarding tutorials. @@ -164,6 +164,8 @@ Keep package or deploy contents intentional. If a file should ship, verify it ap Run `./scripts/check-repository.sh` locally before opening review. This generic check does not replace stack-specific tests, but it catches missing template files, tracked local artifacts, obvious secrets, private paths, and drift in review templates. +Workflows reference actions by their latest major version tag, such as `actions/checkout@v7`, not by commit SHA. Workflow files copied from this template take action upgrades from the template rather than local edits. + ## Local Git Hooks Install local hooks after cloning or creating a repository from this template: diff --git a/README.md b/README.md index 25c436a..86bb878 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Use this template when creating a new project that should have consistent contri - `.github/workflows/review.yml` for generic repository, PR title, and PR description checks. - `.githooks/pre-commit` for local commit-time repository checks. - `.gitlab/merge_request_templates/default.md` for GitLab-style MR summaries. -- `specs/0000-template.md` for active product behavior. +- `docs/specs/0000-template.md` for active product behavior. - `docs/plans/0000-template.md` for active technical decisions and detailed execution plans. - `scripts/check-repository.sh` for local and CI repository checks. - `scripts/check-pr-title.sh` for conventional PR or MR title checks. @@ -53,4 +53,4 @@ Use this template when creating a new project that should have consistent contri Keep this repository generic. Do not add language-specific package files, framework defaults, generated output, or project-specific business logic. -Keep collaboration policy in `AGENTS.md` and `CONTRIBUTING.md`, active behavior in `specs/`, active technical decisions and execution plans in `docs/plans/`, and current product or engineering knowledge in `docs/`. +Keep collaboration policy in `AGENTS.md` and `CONTRIBUTING.md`, active behavior in `docs/specs/`, active technical decisions and execution plans in `docs/plans/`, and current product or engineering knowledge in `docs/`. diff --git a/docs/README.md b/docs/README.md index a585aa8..a49b761 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ Do not create empty directories just to match this list. Add a section when the ## Spec And Plan Boundary -- [`../specs/`](../specs/) declares active product behavior and acceptance contracts. +- [`specs/`](specs/) declares active product behavior and acceptance contracts. - [`plans/`](plans/) contains active technical decisions and detailed execution plans. The Change Design Gate in [`CONTRIBUTING.md`](../CONTRIBUTING.md) decides which artifacts a change needs. After delivery, lasting constraints belong in current-state `docs/`. Git history keeps the retired Spec or Plan. diff --git a/specs/0000-template.md b/docs/specs/0000-template.md similarity index 83% rename from specs/0000-template.md rename to docs/specs/0000-template.md index f2138d5..7e8aba3 100644 --- a/specs/0000-template.md +++ b/docs/specs/0000-template.md @@ -1,6 +1,6 @@ # Spec 0000: Product Behavior -Use this template for an active declarative contract. Follow the [SDD Workflow And Document Lifecycle](../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle) for the complete workflow. +Use this template for an active declarative contract. Follow the [SDD Workflow And Document Lifecycle](../../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle) for the complete workflow. ## Status diff --git a/specs/README.md b/docs/specs/README.md similarity index 70% rename from specs/README.md rename to docs/specs/README.md index f813132..70e812b 100644 --- a/specs/README.md +++ b/docs/specs/README.md @@ -4,4 +4,4 @@ Active Specs define interactions, scope, failure behavior, compatibility, and ac Start from [`0000-template.md`](0000-template.md). Use `Draft`, `Accepted`, or `Superseded`. Give acceptance scenarios stable IDs and use Given/When/Then where useful. Link them to tests. No separate BDD document or framework is required. Technical decisions and the detailed execution plan belong in the paired Plan. -Follow the [SDD lifecycle](../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle): migrate lasting behavior to tests and current-state docs before deleting completed Specs and Plans in the final delivery PR. Keep unfinished work active. +Follow the [SDD lifecycle](../../CONTRIBUTING.md#sdd-workflow-and-document-lifecycle): migrate lasting behavior to tests and current-state docs before deleting completed Specs and Plans in the final delivery PR. Keep unfinished work active. diff --git a/scripts/check-repository.sh b/scripts/check-repository.sh index e8fb69b..cfd2a50 100755 --- a/scripts/check-repository.sh +++ b/scripts/check-repository.sh @@ -66,7 +66,7 @@ required_files=( "scripts/install-git-hooks.sh" "scripts/configure-github-repository.sh" "scripts/lib/review-sections.sh" - "specs/0000-template.md" + "docs/specs/0000-template.md" "docs/plans/0000-template.md" )