From be45dca593b96e99f03d03bb253e6fca314f9920 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Sat, 30 May 2026 21:01:02 +0300 Subject: [PATCH 1/2] docs: add adoption guide, three scenarios, and dogfooding badge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - New adoption-guide.md: step-by-step team rollout (observe → warn → enforce) - New scenarios/: open-source, enterprise, and AI-coding team use cases - Updated README with ODS badge and dogfooding note - Updated docs/index.md with links to new pages --- README.md | 2 + docs/adoption-guide.md | 325 ++++++++++++++++++++++++++ docs/index.md | 3 +- docs/scenarios/ai-coding-pr.md | 254 ++++++++++++++++++++ docs/scenarios/enterprise-service.md | 211 +++++++++++++++++ docs/scenarios/open-source-project.md | 145 ++++++++++++ 6 files changed, 939 insertions(+), 1 deletion(-) create mode 100644 docs/adoption-guide.md create mode 100644 docs/scenarios/ai-coding-pr.md create mode 100644 docs/scenarios/enterprise-service.md create mode 100644 docs/scenarios/open-source-project.md diff --git a/README.md b/README.md index 3c0e71e..ba6dcb6 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ [![CI](https://github.com/open-delivery-spec/spec/actions/workflows/ci.yml/badge.svg)](https://github.com/open-delivery-spec/spec/actions/workflows/ci.yml) [![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](docs/levels.md) +> **Dogfooding:** This repository uses ODS to validate its own PRs. [View the latest compliance report](https://github.com/open-delivery-spec/spec/actions/workflows/ci.yml). + > **ODS does not prove the code is correct. It proves the delivery process contains the minimum structured evidence needed for humans and machines to review the change responsibly.** AI makes coding faster. Everything after coding — review, verification, audit — gets harder. Teams need structured answers to basic delivery governance questions: diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md new file mode 100644 index 0000000..ff784bc --- /dev/null +++ b/docs/adoption-guide.md @@ -0,0 +1,325 @@ +# ODS Adoption Guide + +**For teams that want to adopt ODS without reading the spec first.** + +This guide walks through adopting ODS L1 in a real team, from zero to full enforcement. It is designed to be copied, adapted, and shared with your engineering organization. + +--- + +## Overview + +| Step | What you do | Time | Who | +|------|-------------|------|-----| +| [1](#step-1-add-the-pr-template) | Add PR template | 2 min | One person | +| [2](#step-2-add-the-validate-action) | Add CI validation | 5 min | One person | +| [3](#step-3-make-the-report-visible) | Badge, report, PR comment | 5 min | One person | +| [4](#step-4-team-rollout) | Progressive rollout | 1-2 weeks | Team lead | +| [5](#step-5-add-ai-disclosure) | AI disclosure (optional) | 5 min | Team | +| [6](#step-6-customize-policy) | Customize `.ods.yaml` | 15 min | Team lead | + +--- + +## Step 1: Add the PR Template + +**Goal:** Every new PR starts with the right structure. + +Run `ods init` to scaffold everything, or copy just the PR template: + +```bash +# One-command scaffold (recommended) +ods init github +``` + +Or manually: + +```bash +# Copy the PR template +curl -o .github/PULL_REQUEST_TEMPLATE.md \ + https://raw.githubusercontent.com/open-delivery-spec/spec/main/examples/ods-pr-template.md +``` + +**What changes:** +- `.github/PULL_REQUEST_TEMPLATE.md` — developers see this when opening a PR +- Developers fill in Summary, Changes, Testing, AI Disclosure sections +- No CI enforcement yet — this is just a template + +**Success check:** Open a test PR. The template appears in the description box. + +--- + +## Step 2: Add the validate-action + +**Goal:** CI validates that every PR has the required metadata before merge. + +Add these two workflow files to `.github/workflows/`: + +**`ods-l1.yml`** — validates branch name and PR description on every PR: + +```yaml +name: ODS L1 +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + issues: write + +jobs: + ods: + runs-on: ubuntu-latest + steps: + - uses: open-delivery-spec/validate-action@v1 + with: + check: all + branch_name: ${{ github.head_ref }} + pr_body: ${{ github.event.pull_request.body }} + strict: "true" +``` + +**`ods-commit-message.yml`** — validates commit messages on push: + +```yaml +name: ODS Commit Message +on: [push] + +jobs: + ods-commit: + runs-on: ubuntu-latest + steps: + - uses: open-delivery-spec/validate-action@v1 + with: + check: commit-message + commit_message: ${{ github.event.head_commit.message }} + strict: "true" +``` + +> [!TIP] +> Start with `strict: "false"` to treat warnings as non-blocking. Switch to `"true"` after the team adjusts. + +**What changes:** +- Every PR gets validated for branch naming and PR description +- Every push gets validated for commit message format +- Failed checks block merge (if branch protection is configured) + +**Success check:** Open a PR with a branch like `fix-bug`. The check fails. Rename to `bugfix/fix-null-pointer`. The check passes. + +--- + +## Step 3: Make the Report Visible + +**Goal:** Developers see compliance status without digging into CI logs. + +The validate-action outputs three surfaces by default: + +1. **PR comment** — a compliance report is posted as a comment on every PR +2. **Job summary** — a Markdown summary appears in the Actions run page +3. **Workflow artifact** — HTML, JSON, SVG, and Markdown files downloadable from the run + +Add an ODS badge to your README: + +```markdown +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +``` + +**Success check:** Open a PR. The ODS bot posts a compliance comment. The Actions run shows the summary. + +--- + +## Step 4: Team Rollout + +**Goal:** Adopt ODS across the team without friction. + +Use progressive enforcement: + +### Week 1: Observe + +```yaml +strict: "false" +``` + +- All checks run but warnings don't block merge +- Team gets used to the PR template and branch naming +- Review the ODS compliance report in PR comments — note common failures + +### Week 2: Warn + +Enable branch protection: + +- Require the ODS L1 check to pass before merge +- Team chat: share the most common failures and how to fix them +- Keep `strict: "false"` so only hard errors block + +### Week 3+: Enforce + +```yaml +strict: "true" +``` + +- Warnings become errors +- AI disclosure becomes mandatory (if enabled) +- All PRs are fully ODS L1 compliant before merge + +**Team communication template:** + +> We're adopting [Open Delivery Spec](https://open-delivery-spec.dev) (ODS) to make our PRs easier to review — especially for AI-assisted changes. Starting this week, CI will check that every PR has a structured description and follows branch/commit conventions. The ODS bot posts a compliance report on each PR. This week is observe-only; next week we'll require the check to pass. Questions? See [our adoption guide](.github/ODS-ADOPTION.md). + +--- + +## Step 5: Add AI Disclosure + +**Goal:** Make AI involvement in code changes explicit and machine-checkable. + +If your team uses AI coding tools (Copilot, Cursor, Claude, etc.), enable AI disclosure: + +### Commit messages + +Add AI attribution trailers to commit messages: + +```text +feat(auth): add OAuth login + +AI-assisted: true +AI-tool: GitHub Copilot +AI-scope: token exchange, session management +AI-review: pending +``` + +### PR descriptions + +The PR template already includes the AI Disclosure section: + +```markdown +## AI Disclosure +- [x] This PR contains AI-generated code +- **AI Tool:** GitHub Copilot +- **AI Scope:** Provider abstraction, token exchange +- **Human Review:** Verified OAuth flow, redirect validation +``` + +### Configure enforcement + +In `.ods.yaml`: + +```yaml +policy: + ai_disclosure: + required: true + strict_tool_name: true + require_human_review: true +``` + +**Success check:** Create a PR with AI-generated code but no disclosure. The check warns or fails. + +--- + +## Step 6: Customize Policy + +**Goal:** Tune ODS to your team's conventions. + +Create or edit `.ods.yaml` in your repo root: + +```yaml +profile: enterprise + +policy: + branch: + allowed_types: + - feature + - bugfix + - hotfix + - release + - chore + - docs # add your team's types + require_ticket: false # set true if you use Jira tickets in branch names + max_description_length: 100 + + commit: + allowed_types: + - feat + - fix + - docs + - refactor + - test + - chore + require_scope: true + max_subject_length: 72 + + pr: + required_sections: + - "## Summary" + - "## Changes" + - "## Testing" + - "## Checklist" + # remove sections your team doesn't need + + severity: + branch_type: error + branch_format: error + pr_sections: error + commit_type: error + commit_scope: warning # treat missing scope as a warning +``` + +Available profiles: +- `oss` — no AI disclosure required, relaxed rules +- `enterprise` — full L1 + AI disclosure (recommended) +- `regulated` — maximum enforcement with ticket requirements + +--- + +## Troubleshooting + +### "My branch name fails but our convention uses a different prefix" + +Add your prefix to `.ods.yaml`: + +```yaml +policy: + branch: + allowed_types: [feature, bugfix, hotfix, release, chore, exp] +``` + +### "My commit messages don't use scopes" + +Either add scopes, or relax the rule: + +```yaml +policy: + commit: + require_scope: false + severity: + commit_scope: warning +``` + +### "The PR template has too many sections" + +Remove sections from `required_sections` in `.ods.yaml`: + +```yaml +policy: + pr: + required_sections: + - "## Summary" + - "## Changes" + - "## Testing" +``` + +### "I want to disable PR comments (too noisy)" + +```yaml +- uses: open-delivery-spec/validate-action@v1 + with: + check: all + comment: "false" +``` + +--- + +## Next Steps + +- [Read the spec](https://github.com/open-delivery-spec/spec) to understand the schema details +- [Explore scenarios](https://open-delivery-spec.dev/scenarios/) for your project type +- [Check the roadmap](https://github.com/open-delivery-spec/spec/blob/main/ROADMAP.md) for upcoming features +- [Contribute](https://github.com/open-delivery-spec/spec/blob/main/CONTRIBUTING.md) — ODS is open source diff --git a/docs/index.md b/docs/index.md index d168061..cdb4dc8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,8 +15,9 @@ AI coding tools make changes faster than delivery processes can explain them. Te Open Delivery Spec (ODS) defines a small set of **machine-readable metadata conventions** that CI tools and AI agents can validate before merge. The starting point is **ODS L1 + AI Disclosure**: branch, commit, and PR checks that run in CI today. > **Start here**: [Get Started](get-started) → [PR Template](../examples/ods-pr-template). +> **Adopting in a team**: [Adoption Guide](adoption-guide) — step-by-step rollout. > **See the difference**: [Before & After](case-study). -> **Why this exists**: [Threats & Failure Modes](threats-and-failure-modes). +> **Real-world scenarios**: [Open-source](scenarios/open-source-project) · [Enterprise](scenarios/enterprise-service) · [AI coding team](scenarios/ai-coding-pr). > **Why this exists**: [Threats & Failure Modes](threats-and-failure-modes). > **How it fits**: [ODS and SLSA](comparison/slsa) — SLSA proves how artifacts were built; ODS proves how changes were delivered. > **Artifact storage**: [`.ods/` Convention](ods-artifacts). diff --git a/docs/scenarios/ai-coding-pr.md b/docs/scenarios/ai-coding-pr.md new file mode 100644 index 0000000..7c8d4b0 --- /dev/null +++ b/docs/scenarios/ai-coding-pr.md @@ -0,0 +1,254 @@ +# Scenario: AI-Heavy Coding Team + +**Use case:** A startup team of 4 engineers uses AI coding tools (Cursor, Copilot, Claude) for 60-80% of their code. They ship fast but are losing track of what AI wrote and who reviewed it. They want to keep the speed but add guardrails. + +## Profile + +- Team: 4 engineers +- Repo: Private on GitHub +- AI tools: Cursor (primary), GitHub Copilot (secondary), Claude (architecture discussions) +- AI usage: 60-80% of code is AI-generated or AI-assisted +- Goal: Track AI involvement per PR, ensure human review of AI code, keep CI fast + +## The problem they faced + +> "We shipped a new payment integration in 2 days. It passed CI, passed tests, went to production. Two weeks later we found a race condition in the token refresh logic — AI had hallucinated a non-existent API method. No one had reviewed that specific function because the PR was 800 lines and looked fine at a glance." + +**Root cause:** No structured way to know *where* AI contributed, so reviewers couldn't apply targeted scrutiny. + +## Configuration + +### `.ods.yaml` + +```yaml +profile: enterprise + +policy: + branch: + allowed_types: + - feature + - bugfix + - hotfix + - chore + - exp + + commit: + require_scope: true + + pr: + required_sections: + - "## Summary" + - "## Type" + - "## AI Disclosure" + - "## Changes" + - "## Testing" + - "## Checklist" + + ai_disclosure: + required: true + strict_tool_name: true + require_human_review: true + ai_branch_naming: warning + + severity: + branch_type: error + branch_format: error + pr_sections: error + pr_ai_disclosure: error + pr_ai_tool: error + commit_type: error + commit_scope: warning + commit_ai: error +``` + +### Agent instructions + +Add to `.cursorrules`, `.claude.md`, or `.github/copilot-instructions.md`: + +```markdown +## ODS Compliance + +When creating branches, commits, or PR descriptions, follow Open Delivery Spec L1: + +### Branch naming +- Use `/` format +- Types: feature, bugfix, hotfix, chore, exp +- Example: `feature/add-oauth-login` + +### Commit messages +- Use Conventional Commits: `(): ` +- If this commit contains AI-generated code, add trailers: + ``` + AI-assisted: true + AI-tool: Cursor + AI-scope: + AI-review: pending + ``` + +### PR descriptions +- Always include these sections: + - ## Summary + - ## Type + - ## AI Disclosure (REQUIRED if any AI tool was used) + - ## Changes + - ## Testing + - ## Checklist +- Be specific in AI Disclosure about what was AI-generated and what you personally verified +``` + +### `.github/workflows/ods-l1.yml` + +```yaml +name: ODS L1 +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + issues: write + +jobs: + ods: + runs-on: ubuntu-latest + steps: + - uses: open-delivery-spec/validate-action@v1 + with: + check: all + branch_name: ${{ github.head_ref }} + pr_body: ${{ github.event.pull_request.body }} + strict: "true" +``` + +## Before / After + +### Before ODS — a typical AI-assisted PR + +``` +Title: add payment integration +Branch: payment-integration +Commit: add payment stuff + +PR body: + Added the new payment provider integration. + Works on my machine. + +Reviewer (looking at 800-line diff): + - "Which parts are generated vs hand-written?" + - "Did you verify the token refresh logic?" + - "Have you tested the webhook handler?" +``` + +**Result:** Reviewer skims the diff, approves. Race condition ships to production. + +### After ODS — same change, structured + +``` +Title: feat(payments): add Stripe payment provider integration + +Branch: feature/stripe-payment-provider + +Commit: + feat(payments): add Stripe provider with webhook handling + + AI-assisted: true + AI-tool: Cursor + AI-scope: Stripe API client, webhook signature verification, token refresh + AI-review: pending + +PR body: + ## Summary + Adds Stripe as a new payment provider. Integrates checkout sessions, + webhook handling, and automatic token refresh. + + ## AI Disclosure + - [x] This PR contains AI-generated code + - AI Tool: Cursor (primary), GitHub Copilot (test generation) + - AI Scope: + - Stripe API client class (generate) + - Webhook signature verification (generate) + - Token refresh logic (generate) + - Test cases for webhook handler (Copilot) + - Human Review: + - Verified Stripe API documentation for all endpoint signatures + - Validated webhook signature against Stripe's recommended approach + - Manually tested webhook with Stripe CLI + - Reviewed token refresh for race conditions + - Rewrote error handling for API timeouts + + ## Changes + - Added Stripe API client with automatic retry and timeout + - Added webhook endpoint with signature verification + - Added token refresh on 401 responses + - Added unit tests for all new modules + - Added integration tests with Stripe test mode + + ## Testing + - [x] Unit tests pass (coverage: 94%) + - [x] Integration tests pass with Stripe test keys + - [x] Manual testing with Stripe CLI webhook forwarding + - [x] Tested token expiry and refresh cycle + - [x] Tested network timeout and retry behavior + + ## Checklist + - [x] Branch naming follows ODS + - [x] Commits include AI attribution + - [x] All AI-generated code has been reviewed by a human + - [x] No secrets or credentials in code + - [x] Stripe test keys only (no production keys) + +Reviewer: + - Immediately sees what AI generated → focuses scrutiny there + - Reads human review notes → trusts that Stripe docs were checked + - Sees testing details → confident about edge cases + - Approves with 0 clarification questions +``` + +**Result:** Reviewer spends time on the AI-generated token refresh logic, catches the hallucinated API method before merge. The PR takes 15 minutes to review instead of 5 — but the bug doesn't reach production. + +## What changes for the team + +### Daily workflow + +1. **Engineer starts a feature** → creates branch `feature/stripe-integration` +2. **AI generates most of the code** → engineer reviews AI output, adjusts, commits with AI trailers +3. **Engineer opens PR** → PR template prefills. Engineer fills AI Disclosure with specifics +4. **CI runs ODS L1** → validates branch name, PR sections, AI disclosure completeness +5. **ODS bot comments** → compliance report with pass/fail for each check +6. **Reviewer reads AI Disclosure first** → focuses on AI-generated areas +7. **PR merges** → AI disclosure is permanently recorded in the PR + +### Reviewer behavior change + +| Before | After | +|--------|-------| +| Read entire diff top to bottom | Read AI Disclosure first, then review AI-generated code more carefully | +| Trust that engineer tested everything | See specific testing claims, ask follow-ups on gaps | +| Assume all code is hand-written | Know exactly what AI contributed | + +### Metrics to track + +- **Review time per PR** — may increase initially (more thorough), stabilizes as reviewers learn to focus +- **Bugs found in review vs. production** — should shift toward review +- **AI disclosure completeness** — % of AI-assisted PRs with complete AI Disclosure sections +- **Reviewer questions per PR** — should decrease as PRs contain more context + +## Badge + +```markdown +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +``` + +## Lessons learned + +1. **AI Disclosure is the highest-value section.** It changes reviewer behavior immediately. +2. **Agent instructions matter.** Adding ODS conventions to `.cursorrules` means the AI generates compliant branches and commit messages by default. +3. **Don't skip commit trailers.** `AI-assisted: true` in commits means even squashed PRs carry AI attribution into the main branch. +4. **Start with strict.** AI-heavy teams benefit from enforcement from day 1. The team already has the discipline to use AI tools; adding structured metadata is a smaller lift than for teams new to both. + +## Next steps after adoption + +1. When the team grows, add `.ods.yaml` to the shared engineering standards repo +2. Explore [Module 04 (AI Change Review)](../spec/04-ai-change-review.md) for structured review records of AI-generated code +3. If shipping to regulated customers, explore [Module 09 (Production Evidence)](../spec/09-prod-release-evidence.md) for deployment audit trails diff --git a/docs/scenarios/enterprise-service.md b/docs/scenarios/enterprise-service.md new file mode 100644 index 0000000..1f0cd51 --- /dev/null +++ b/docs/scenarios/enterprise-service.md @@ -0,0 +1,211 @@ +# Scenario: Enterprise Internal Service + +**Use case:** A platform team owns 3 internal services. They want consistent delivery metadata across all repos, AI disclosure for Copilot-heavy development, and audit-ready PR records. + +## Profile + +- Team: 8 engineers, 3 services +- Repo: Private on GitHub Enterprise +- AI tools: Entire team uses GitHub Copilot (organization-wide) +- Regulation: Internal audit requires evidence of human review for all production changes +- Goal: Full ODS L1 + AI Disclosure enforced before merge, with compliance reports archived + +## Configuration + +### `.ods.yaml` + +```yaml +profile: enterprise + +policy: + branch: + allowed_types: + - feature + - bugfix + - hotfix + - release + - chore + require_ticket: true + max_description_length: 80 + + commit: + require_scope: true + max_subject_length: 72 + + pr: + required_sections: + - "## Summary" + - "## Type" + - "## AI Disclosure" + - "## Changes" + - "## Testing" + - "## Risk Assessment" + - "## Checklist" + min_changes: 1 + + ai_disclosure: + required: true + strict_tool_name: true + require_human_review: true + ai_branch_naming: warning + + severity: + branch_type: error + branch_format: error + pr_sections: error + pr_ai_disclosure: error + pr_ai_tool: error + commit_type: error + commit_scope: error + commit_ai: error +``` + +### `.github/workflows/ods-l1.yml` + +```yaml +name: ODS L1 +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + issues: write + +jobs: + ods: + runs-on: ubuntu-latest + steps: + - uses: open-delivery-spec/validate-action@v1 + with: + check: all + branch_name: ${{ github.head_ref }} + pr_body: ${{ github.event.pull_request.body }} + strict: "true" + artifact-retention-days: "90" +``` + +### `.github/workflows/ods-commit-message.yml` + +```yaml +name: ODS Commit Message +on: [push] + +jobs: + ods-commit: + runs-on: ubuntu-latest + steps: + - uses: open-delivery-spec/validate-action@v1 + with: + check: commit-message + commit_message: ${{ github.event.head_commit.message }} + strict: "true" +``` + +### `.github/PULL_REQUEST_TEMPLATE.md` + +Full template from [ods-pr-template.md](../examples/ods-pr-template.md). + +### Branch protection rules + +- Require `ODS L1` status check to pass before merge +- Require at least 1 approving review +- Require conversation resolution + +## Rollout plan + +### Week 1-2: Template + Observe + +- Add PR template and workflows +- `strict: "false"` — CI reports but doesn't block +- Share the [adoption guide](../adoption-guide.md) in team Slack + +### Week 3-4: Warn + +- Team demo: show the ODS PR comment, job summary, and artifact +- Review common failures from the first two weeks. Adjust `.ods.yaml` if needed +- `strict: "true"` on `ods-l1.yml` for branch and PR checks only + +### Week 5+: Enforce + +- `strict: "true"` on both workflows +- Enable branch protection requiring ODS check +- Archive compliance reports for audit (90-day retention) + +## What the team sees + +### Passing PR + +The ODS bot posts a comment: + +``` +## ODS Compliance Report + +Status: ✅ ODS L1 Compliant +Score: 100 / 100 +Profile: L1 - AI-aware delivery metadata + +Repository: acme-corp/user-service +Ref: feature/PROJ-423-oauth-migration +Commit: a1b2c3d4e5f6 +Pull request: #423 + +| Check | Result | Notes | +|---|---|---| +| Branch naming | ✅ Pass | feature/PROJ-423-oauth-migration | +| Commit message | ✅ Pass | feat(auth): migrate OAuth to PKCE flow | +| PR description | ✅ Pass | - | +``` + +### Failing PR + +``` +## ODS Compliance Report + +Status: ❌ ODS L1 Non-Compliant +Score: 33 / 100 + +| Check | Result | Notes | +|---|---|---| +| Branch naming | ✅ Pass | bugfix/fix-token-expiry | +| Commit message | ❌ Fail | fix stuff; missing scope | +| PR description | ❌ Fail | missing section: AI Disclosure; missing section: Risk Assessment | +``` + +## Audit trail + +For each release, the compliance team downloads: + +1. **Workflow artifact** — `ods-compliance-report.zip` containing HTML, JSON, SVG, Markdown +2. **PR comment** — permanent record of the ODS report at merge time +3. **AI disclosure records** — structured evidence of what AI generated and who reviewed it + +These satisfy internal audit requirements: +- Traceability: which engineer reviewed which AI-generated change +- Human oversight: documented per PR +- Delivery governance: consistent metadata across all repos + +## Badge + +```markdown +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +``` + +## Multi-repo adoption + +For the platform team's 3 services, copy the same three files to each repo: + +```bash +# In each service repo: +ods init github +# Then customize .ods.yaml if any service has specific conventions +``` + +Use a shared `.ods.yaml` template in your team's engineering standards repo and reference it from each service. + +## Next steps after adoption + +1. Integrate ODS report artifacts into your release checklist pipeline +2. Map ODS AI Disclosure fields to your internal audit control framework +3. When ready, explore [Module 06 (Release Readiness)](../spec/06-release-readiness.md) and [Module 09 (Production Evidence)](../spec/09-prod-release-evidence.md) for release-governance gates diff --git a/docs/scenarios/open-source-project.md b/docs/scenarios/open-source-project.md new file mode 100644 index 0000000..b7cbf6d --- /dev/null +++ b/docs/scenarios/open-source-project.md @@ -0,0 +1,145 @@ +# Scenario: Open-Source Project + +**Use case:** A maintainer of an open-source library wants cleaner PR reviews without adding overhead for casual contributors. + +## Profile + +- Team: 1-3 maintainers, 5-50 contributors +- Repo: Public on GitHub +- AI tools: Some contributors use Copilot, but it's not tracked +- Regulation: None +- Goal: Make PRs easier to review, not enforce compliance + +## Configuration + +### `.ods.yaml` + +```yaml +profile: oss + +policy: + branch: + allowed_types: + - feature + - bugfix + - hotfix + - docs + - chore + + commit: + require_scope: false + + pr: + required_sections: + - "## Summary" + - "## Changes" + - "## Testing" + + ai_disclosure: + required: false + + severity: + branch_type: warning + branch_format: warning + pr_sections: warning + commit_type: warning +``` + +### `.github/workflows/ods-l1.yml` + +```yaml +name: ODS L1 +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + ods: + runs-on: ubuntu-latest + steps: + - uses: open-delivery-spec/validate-action@v1 + with: + check: all + branch_name: ${{ github.head_ref }} + pr_body: ${{ github.event.pull_request.body }} + strict: "false" +``` + +### `.github/PULL_REQUEST_TEMPLATE.md` + +```markdown +## Summary + + +## Changes +- +- + +## Testing +- [ ] Tests pass locally +- [ ] New tests added (if applicable) + +## Checklist +- [ ] I have read the contributing guide +- [ ] My changes don't break existing functionality +``` + +## Why this approach + +| Principle | Implementation | +|-----------|----------------| +| **Low barrier** | No AI disclosure, no required scopes, no ticket references | +| **Warnings only** | `strict: "false"` — CI shows issues but never blocks first-time contributors | +| **Minimal template** | Only 3 sections. Contributors fill it in 30 seconds | +| **Upgrade path** | If the project grows, switch `profile` from `oss` to `enterprise` and tighten rules | + +## What the maintainer sees + +**Before ODS:** + +``` +Title: fix bug +Branch: patch-1 +PR body: (empty) + +Maintainer questions: + - "What bug?" + - "How was it tested?" + - "Is this safe to merge?" +``` + +**After ODS:** + +``` +Title: fix(parser): handle empty input in JSON parser +Branch: bugfix/empty-json-input +PR body: + ## Summary + The JSON parser panics when given an empty string input. + + ## Changes + - Added nil check before parsing + - Added test for empty input edge case + + ## Testing + - [x] Tests pass locally + - [x] New tests added + +Maintainer: Merges immediately. +``` + +## Badge + +```markdown +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +``` + +## Next steps after adoption + +1. If the project grows to 5+ regular contributors, switch to `profile: enterprise` +2. If contributors start using AI tools, enable `ai_disclosure.required: true` as a warning first +3. Add `ods-commit-message.yml` workflow for commit message validation on push From 16bf73136b5ad4de833ca7385a59d4d8cc1951e3 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Sat, 30 May 2026 21:06:33 +0300 Subject: [PATCH 2/2] fix: replace non-existent open-delivery-spec.dev with real URLs Use github.com/open-delivery-spec/spec for badge/project links, open-delivery-spec.github.io/spec for docs pages. --- docs/adoption-guide.md | 6 +++--- docs/scenarios/ai-coding-pr.md | 2 +- docs/scenarios/enterprise-service.md | 2 +- docs/scenarios/open-source-project.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md index ff784bc..72b1997 100644 --- a/docs/adoption-guide.md +++ b/docs/adoption-guide.md @@ -120,7 +120,7 @@ The validate-action outputs three surfaces by default: Add an ODS badge to your README: ```markdown -[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://github.com/open-delivery-spec/spec) ``` **Success check:** Open a PR. The ODS bot posts a compliance comment. The Actions run shows the summary. @@ -163,7 +163,7 @@ strict: "true" **Team communication template:** -> We're adopting [Open Delivery Spec](https://open-delivery-spec.dev) (ODS) to make our PRs easier to review — especially for AI-assisted changes. Starting this week, CI will check that every PR has a structured description and follows branch/commit conventions. The ODS bot posts a compliance report on each PR. This week is observe-only; next week we'll require the check to pass. Questions? See [our adoption guide](.github/ODS-ADOPTION.md). +> We're adopting [Open Delivery Spec](https://github.com/open-delivery-spec/spec) (ODS) to make our PRs easier to review — especially for AI-assisted changes. Starting this week, CI will check that every PR has a structured description and follows branch/commit conventions. The ODS bot posts a compliance report on each PR. This week is observe-only; next week we'll require the check to pass. Questions? See [our adoption guide](.github/ODS-ADOPTION.md). --- @@ -320,6 +320,6 @@ policy: ## Next Steps - [Read the spec](https://github.com/open-delivery-spec/spec) to understand the schema details -- [Explore scenarios](https://open-delivery-spec.dev/scenarios/) for your project type +- [Explore scenarios](https://open-delivery-spec.github.io/spec/scenarios/) for your project type - [Check the roadmap](https://github.com/open-delivery-spec/spec/blob/main/ROADMAP.md) for upcoming features - [Contribute](https://github.com/open-delivery-spec/spec/blob/main/CONTRIBUTING.md) — ODS is open source diff --git a/docs/scenarios/ai-coding-pr.md b/docs/scenarios/ai-coding-pr.md index 7c8d4b0..e71f067 100644 --- a/docs/scenarios/ai-coding-pr.md +++ b/docs/scenarios/ai-coding-pr.md @@ -237,7 +237,7 @@ Reviewer: ## Badge ```markdown -[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://github.com/open-delivery-spec/spec) ``` ## Lessons learned diff --git a/docs/scenarios/enterprise-service.md b/docs/scenarios/enterprise-service.md index 1f0cd51..4c6efcb 100644 --- a/docs/scenarios/enterprise-service.md +++ b/docs/scenarios/enterprise-service.md @@ -189,7 +189,7 @@ These satisfy internal audit requirements: ## Badge ```markdown -[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://github.com/open-delivery-spec/spec) ``` ## Multi-repo adoption diff --git a/docs/scenarios/open-source-project.md b/docs/scenarios/open-source-project.md index b7cbf6d..a66a637 100644 --- a/docs/scenarios/open-source-project.md +++ b/docs/scenarios/open-source-project.md @@ -135,7 +135,7 @@ Maintainer: Merges immediately. ## Badge ```markdown -[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://open-delivery-spec.dev) +[![ODS L1](https://img.shields.io/badge/ODS-L1%20Structured%20Delivery-blue)](https://github.com/open-delivery-spec/spec) ``` ## Next steps after adoption