Skip to content

Commit ca1341c

Browse files
infracoreclaude
infracore
and
claude
committed
Initial docs site with 38 pages including 27 change type references
- Home, Quick Start, CLI Reference, GitHub Action, MCP Server, Policies, Hooks - 27 individual change type pages with SEO metadata, JSON-LD, examples, migration guides - 3 integration pages (Claude Code, Codex, Gemini CLI) - Dark theme CSS, responsive layout with sidebar navigation - GitHub Pages deployment workflow - All content sourced from diff_engine_v2.py (17 breaking, 10 non-breaking change types) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
0 parents  commit ca1341c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+5829
-0
lines changed

‎.github/workflows/pages.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Deploy Docs
2+
on:
3+
push:
4+
branches: [main]
5+
permissions:
6+
pages: write
7+
id-token: write
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
environment:
12+
name: github-pages
13+
url: ${{ steps.deployment.outputs.page_url }}
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: actions/configure-pages@v4
17+
- uses: actions/upload-pages-artifact@v3
18+
with:
19+
path: '.'
20+
- uses: actions/deploy-pages@v4
21+
id: deployment

‎action/index.html‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>GitHub Action Setup - Delimit Docs</title>
7+
<meta name="description" content="Add Delimit API governance to your GitHub CI pipeline. Catch breaking OpenAPI changes on every pull request with advisory or enforce mode.">
8+
<link rel="canonical" href="https://delimit-ai.github.io/docs/action/">
9+
<link rel="stylesheet" href="/docs/style.css">
10+
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>&#x1f6e1;</text></svg>">
11+
12+
</head>
13+
<body>
14+
<nav class="sidebar">
15+
<a href="/docs/" class="logo">Delimit</a>
16+
<ul>
17+
<li><a href="/docs/">Home</a></li>
18+
<li><a href="/docs/quickstart/">Quick Start</a></li>
19+
<li><a href="/docs/cli/">CLI Reference</a></li>
20+
<li><a href="/docs/action/" class="active">GitHub Action</a></li>
21+
<li><a href="/docs/mcp/">MCP Server</a></li>
22+
<li><a href="/docs/policies/">Policies</a></li>
23+
<li><a href="/docs/hooks/">Hooks</a></li>
24+
<li><a href="/docs/changes/">Change Types</a></li>
25+
<li><a href="/docs/integrations/claude-code.html">Integrations</a></li>
26+
</ul>
27+
<div class="sidebar-footer">
28+
<a href="https://github.com/delimit-ai/delimit-action" target="_blank">GitHub</a>
29+
<a href="https://www.npmjs.com/package/delimit-cli" target="_blank">npm</a>
30+
<a href="https://delimit.ai" target="_blank">delimit.ai</a>
31+
</div>
32+
</nav>
33+
34+
<main>
35+
36+
<h1>GitHub Action</h1>
37+
<p class="lead">Add API governance to your CI pipeline with the Delimit GitHub Action.</p>
38+
39+
<h2>Installation</h2>
40+
<p>Available on the <a href="https://github.com/marketplace/actions/delimit-api-governance" target="_blank">GitHub Marketplace</a>.</p>
41+
42+
<h2>Basic Setup</h2>
43+
<p>Create <code>.github/workflows/api-governance.yml</code>:</p>
44+
<pre><code>name: API Governance
45+
on:
46+
pull_request:
47+
paths: ["openapi.yaml"]
48+
49+
jobs:
50+
delimit:
51+
runs-on: ubuntu-latest
52+
steps:
53+
- uses: actions/checkout@v4
54+
- uses: delimit-ai/delimit-action@v1
55+
with:
56+
spec: openapi.yaml</code></pre>
57+
58+
<h2>Inputs</h2>
59+
<table>
60+
<thead>
61+
<tr><th>Input</th><th>Description</th><th>Default</th></tr>
62+
</thead>
63+
<tbody>
64+
<tr><td><code>spec</code></td><td>Path to OpenAPI spec. Delimit auto-fetches the base branch version.</td><td><em>auto-detect</em></td></tr>
65+
<tr><td><code>old_spec</code></td><td>Path to old/base spec (advanced mode).</td><td></td></tr>
66+
<tr><td><code>new_spec</code></td><td>Path to new/changed spec (advanced mode).</td><td></td></tr>
67+
<tr><td><code>mode</code></td><td><code>advisory</code> (comments only) or <code>enforce</code> (fail CI).</td><td><code>advisory</code></td></tr>
68+
<tr><td><code>github_token</code></td><td>Token for PR comments.</td><td><code>${{ github.token }}</code></td></tr>
69+
<tr><td><code>policy_file</code></td><td>Path to custom policy file.</td><td></td></tr>
70+
</tbody>
71+
</table>
72+
73+
<h2>Outputs</h2>
74+
<table>
75+
<thead>
76+
<tr><th>Output</th><th>Description</th></tr>
77+
</thead>
78+
<tbody>
79+
<tr><td><code>breaking_changes_detected</code></td><td><code>true</code> or <code>false</code></td></tr>
80+
<tr><td><code>violations_count</code></td><td>Number of policy violations</td></tr>
81+
<tr><td><code>semver_bump</code></td><td><code>major</code>, <code>minor</code>, <code>patch</code>, or <code>none</code></td></tr>
82+
<tr><td><code>next_version</code></td><td>Computed next version string</td></tr>
83+
<tr><td><code>report</code></td><td>Full JSON report of all changes</td></tr>
84+
</tbody>
85+
</table>
86+
87+
<h2>Advisory vs Enforce Mode</h2>
88+
<p><strong>Advisory mode</strong> (default): Delimit posts a PR comment with the diff report but does not block the merge. Good for initial adoption.</p>
89+
<p><strong>Enforce mode</strong>: Delimit blocks the merge if breaking changes are detected. Use this once your team is comfortable with the governance workflow.</p>
90+
<pre><code>- uses: delimit-ai/delimit-action@v1
91+
with:
92+
spec: openapi.yaml
93+
mode: enforce</code></pre>
94+
95+
<h2>Advanced: Two-Spec Mode</h2>
96+
<p>For monorepos or custom setups where you manage both spec files:</p>
97+
<pre><code>- uses: delimit-ai/delimit-action@v1
98+
with:
99+
old_spec: specs/api-v1.yaml
100+
new_spec: specs/api-v2.yaml
101+
mode: enforce
102+
policy_file: .delimit/policies.yml</code></pre>
103+
104+
<h2>Auto-Detection</h2>
105+
<p>If no spec input is provided, Delimit searches for common spec file names: <code>openapi.yaml</code>, <code>openapi.yml</code>, <code>openapi.json</code>, <code>swagger.yaml</code>, etc. in the root and common subdirectories (<code>api/</code>, <code>docs/</code>, <code>spec/</code>).</p>
106+
107+
<h2>PR Comment</h2>
108+
<p>Delimit automatically posts (and updates) a PR comment showing:</p>
109+
<ul>
110+
<li>Breaking changes with severity levels</li>
111+
<li>Semver recommendation</li>
112+
<li>Migration guide for each breaking change</li>
113+
<li>Additive (non-breaking) changes</li>
114+
</ul>
115+
116+
</main>
117+
<footer>
118+
<p>Delimit &mdash; API governance for AI coding assistants &middot;
119+
<a href="https://delimit.ai">delimit.ai</a> &middot;
120+
<a href="https://github.com/delimit-ai/delimit-action">GitHub</a> &middot;
121+
<a href="https://www.npmjs.com/package/delimit-cli">npm</a>
122+
</p>
123+
</footer>
124+
</body>
125+
</html>

‎changes/default-changed.html‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>default_changed - Non-Breaking API Change Detection - Delimit Docs</title>
7+
<meta name="description" content="Detect default_changed changes in OpenAPI specs. The default value of a parameter or field has changed. Consumers relying on the old default behavior will see different ">
8+
<link rel="canonical" href="https://delimit-ai.github.io/docs/changes/default-changed.html">
9+
<link rel="stylesheet" href="/docs/style.css">
10+
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>&#x1f6e1;</text></svg>">
11+
<script type="application/ld+json">{"@context": "https://schema.org", "@type": "TechArticle", "headline": "default_changed - API Change Detection", "description": "The default value of a parameter or field has changed. Consumers relying on the old default behavior will see different results.", "url": "https://delimit-ai.github.io/docs/changes/default-changed.html", "author": {"@type": "Organization", "name": "Delimit AI"}, "publisher": {"@type": "Organization", "name": "Delimit AI", "url": "https://delimit.ai"}, "keywords": "openapi default value changed non-breaking change parameter schema", "about": {"@type": "Thing", "name": "default_changed", "description": "The default value of a parameter or field has changed. Consumers relying on the old default behavior will see different results."}}</script>
12+
</head>
13+
<body>
14+
<nav class="sidebar">
15+
<a href="/docs/" class="logo">Delimit</a>
16+
<ul>
17+
<li><a href="/docs/">Home</a></li>
18+
<li><a href="/docs/quickstart/">Quick Start</a></li>
19+
<li><a href="/docs/cli/">CLI Reference</a></li>
20+
<li><a href="/docs/action/">GitHub Action</a></li>
21+
<li><a href="/docs/mcp/">MCP Server</a></li>
22+
<li><a href="/docs/policies/">Policies</a></li>
23+
<li><a href="/docs/hooks/">Hooks</a></li>
24+
<li><a href="/docs/changes/" class="active">Change Types</a></li>
25+
<li><a href="/docs/integrations/claude-code.html">Integrations</a></li>
26+
</ul>
27+
<div class="sidebar-footer">
28+
<a href="https://github.com/delimit-ai/delimit-action" target="_blank">GitHub</a>
29+
<a href="https://www.npmjs.com/package/delimit-cli" target="_blank">npm</a>
30+
<a href="https://delimit.ai" target="_blank">delimit.ai</a>
31+
</div>
32+
</nav>
33+
34+
<main>
35+
36+
<div class="breadcrumb"><a href="/docs/changes/">Change Types</a> &raquo; default_changed</div>
37+
38+
<h1><code>default_changed</code></h1>
39+
<div class="badge-row">
40+
<span class="badge non-breaking">Non-Breaking</span>
41+
<span class="badge severity-low">Severity: low</span>
42+
</div>
43+
44+
<p class="lead">The default value of a parameter or field has changed. Consumers relying on the old default behavior will see different results.</p>
45+
46+
<h2>Why Is This Non-Breaking?</h2>
47+
<p>Classified as non-breaking because consumers explicitly setting the value are unaffected. However, consumers relying on the default (by omitting the parameter) will experience behavior changes. Review carefully.</p>
48+
49+
<h2>Example</h2>
50+
<div class="diff-container">
51+
<div class="diff-panel">
52+
<h4>Before</h4>
53+
<pre><code>parameters:
54+
- name: limit
55+
in: query
56+
schema:
57+
type: integer
58+
default: 20</code></pre>
59+
</div>
60+
<div class="diff-panel">
61+
<h4>After</h4>
62+
<pre><code>parameters:
63+
- name: limit
64+
in: query
65+
schema:
66+
type: integer
67+
default: 50</code></pre>
68+
</div>
69+
</div>
70+
71+
<h2>How Delimit Detects It</h2>
72+
<p>Delimit compares <code>default</code> values on parameters and schema properties. Any change in the default value is flagged as <code>default_changed</code>.</p>
73+
74+
<h2>Migration Guide</h2>
75+
<p>1. Communicate the default value change to consumers.
76+
2. Consumers relying on the default should explicitly set the old value if they need the previous behavior.
77+
3. Update documentation to reflect the new default.
78+
4. Consider whether this warrants a MINOR version bump in your API.</p>
79+
80+
<h2>Related Change Types</h2>
81+
<ul>
82+
<li><a href="/docs/changes/type-changed.html"><code>type_changed</code></a></li>
83+
<li><a href="/docs/changes/format-changed.html"><code>format_changed</code></a></li>
84+
</ul>
85+
86+
<h2>Detect This Change</h2>
87+
<pre><code>npx delimit-cli lint --old old-spec.yaml --new new-spec.yaml</code></pre>
88+
<p>Or add the <a href="/docs/action/">GitHub Action</a> to catch this automatically on every pull request.</p>
89+
90+
</main>
91+
<footer>
92+
<p>Delimit &mdash; API governance for AI coding assistants &middot;
93+
<a href="https://delimit.ai">delimit.ai</a> &middot;
94+
<a href="https://github.com/delimit-ai/delimit-action">GitHub</a> &middot;
95+
<a href="https://www.npmjs.com/package/delimit-cli">npm</a>
96+
</p>
97+
</footer>
98+
</body>
99+
</html>

‎changes/deprecated-added.html‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>deprecated_added - Non-Breaking API Change Detection - Delimit Docs</title>
7+
<meta name="description" content="Detect deprecated_added changes in OpenAPI specs. An operation or field has been marked as &lt;code&gt;deprecated: true&lt;/code&gt;. This signals intent to remove but does not break">
8+
<link rel="canonical" href="https://delimit-ai.github.io/docs/changes/deprecated-added.html">
9+
<link rel="stylesheet" href="/docs/style.css">
10+
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>&#x1f6e1;</text></svg>">
11+
<script type="application/ld+json">{"@context": "https://schema.org", "@type": "TechArticle", "headline": "deprecated_added - API Change Detection", "description": "An operation or field has been marked as <code>deprecated: true</code>. This signals intent to remove but does not break existing consumers.", "url": "https://delimit-ai.github.io/docs/changes/deprecated-added.html", "author": {"@type": "Organization", "name": "Delimit AI"}, "publisher": {"@type": "Organization", "name": "Delimit AI", "url": "https://delimit.ai"}, "keywords": "openapi deprecated added non-breaking change sunset warning", "about": {"@type": "Thing", "name": "deprecated_added", "description": "An operation or field has been marked as <code>deprecated: true</code>. This signals intent to remove but does not break existing consumers."}}</script>
12+
</head>
13+
<body>
14+
<nav class="sidebar">
15+
<a href="/docs/" class="logo">Delimit</a>
16+
<ul>
17+
<li><a href="/docs/">Home</a></li>
18+
<li><a href="/docs/quickstart/">Quick Start</a></li>
19+
<li><a href="/docs/cli/">CLI Reference</a></li>
20+
<li><a href="/docs/action/">GitHub Action</a></li>
21+
<li><a href="/docs/mcp/">MCP Server</a></li>
22+
<li><a href="/docs/policies/">Policies</a></li>
23+
<li><a href="/docs/hooks/">Hooks</a></li>
24+
<li><a href="/docs/changes/" class="active">Change Types</a></li>
25+
<li><a href="/docs/integrations/claude-code.html">Integrations</a></li>
26+
</ul>
27+
<div class="sidebar-footer">
28+
<a href="https://github.com/delimit-ai/delimit-action" target="_blank">GitHub</a>
29+
<a href="https://www.npmjs.com/package/delimit-cli" target="_blank">npm</a>
30+
<a href="https://delimit.ai" target="_blank">delimit.ai</a>
31+
</div>
32+
</nav>
33+
34+
<main>
35+
36+
<div class="breadcrumb"><a href="/docs/changes/">Change Types</a> &raquo; deprecated_added</div>
37+
38+
<h1><code>deprecated_added</code></h1>
39+
<div class="badge-row">
40+
<span class="badge non-breaking">Non-Breaking</span>
41+
<span class="badge severity-low">Severity: low</span>
42+
</div>
43+
44+
<p class="lead">An operation or field has been marked as <code>deprecated: true</code>. This signals intent to remove but does not break existing consumers.</p>
45+
46+
<h2>Why Is This Non-Breaking?</h2>
47+
<p>This is a non-breaking change. Deprecation is a warning, not a removal. The deprecated element continues to function. It signals that consumers should plan to migrate.</p>
48+
49+
<h2>Example</h2>
50+
<div class="diff-container">
51+
<div class="diff-panel">
52+
<h4>Before</h4>
53+
<pre><code>paths:
54+
/users/search:
55+
get:
56+
summary: Search users</code></pre>
57+
</div>
58+
<div class="diff-panel">
59+
<h4>After</h4>
60+
<pre><code>paths:
61+
/users/search:
62+
get:
63+
summary: Search users
64+
deprecated: true</code></pre>
65+
</div>
66+
</div>
67+
68+
<h2>How Delimit Detects It</h2>
69+
<p>Delimit compares the <code>deprecated</code> flag on operations and schema properties. A change from <code>false</code> (or absent) to <code>true</code> is flagged.</p>
70+
71+
<h2>Migration Guide</h2>
72+
<p>No immediate migration needed. Plan to migrate away from the deprecated element before it is removed. Check the API changelog for the planned removal date.</p>
73+
74+
<h2>Related Change Types</h2>
75+
<ul>
76+
<li><a href="/docs/changes/endpoint-removed.html"><code>endpoint_removed</code></a></li>
77+
<li><a href="/docs/changes/method-removed.html"><code>method_removed</code></a></li>
78+
<li><a href="/docs/changes/field-removed.html"><code>field_removed</code></a></li>
79+
</ul>
80+
81+
<h2>Detect This Change</h2>
82+
<pre><code>npx delimit-cli lint --old old-spec.yaml --new new-spec.yaml</code></pre>
83+
<p>Or add the <a href="/docs/action/">GitHub Action</a> to catch this automatically on every pull request.</p>
84+
85+
</main>
86+
<footer>
87+
<p>Delimit &mdash; API governance for AI coding assistants &middot;
88+
<a href="https://delimit.ai">delimit.ai</a> &middot;
89+
<a href="https://github.com/delimit-ai/delimit-action">GitHub</a> &middot;
90+
<a href="https://www.npmjs.com/package/delimit-cli">npm</a>
91+
</p>
92+
</footer>
93+
</body>
94+
</html>

0 commit comments

Comments
 (0)