Skip to content

Commit fdffbc1

Browse files
devin-ai-integration[bot]aaronsteers
devin-ai-integration[bot]
and
aaronsteers
committed
docs: add CONTRIBUTING.md, AGENTS.md with generation lineage and guidelines
- CONTRIBUTING.md: Full contributor guide with code generation lineage diagram, maintainer regeneration/release/pre-release instructions, drift debugging guide, Speakeasy CLI version pinning explanation, and poe task reference - AGENTS.md: Agent-specific guidelines with safe/unsafe file lists, build commands, and generation instructions Co-Authored-By: AJ Steers <aj@airbyte.io>
1 parent f9ea00b commit fdffbc1

2 files changed

Lines changed: 182 additions & 15 deletions

File tree

‎AGENTS.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Agent Guidelines for airbyte-api-python-sdk
2+
3+
For the full contributor guide (code generation lineage, build commands, release process, and debugging generation drift), see [CONTRIBUTING.md](CONTRIBUTING.md).
4+
5+
## Key Principle: This Is a Generated Codebase
6+
7+
Most code under `src/airbyte_api/` is generated by Speakeasy. **Do not hand-edit generated files.** To make durable changes, work at the correct layer (overlay, post-generation script, or upstream spec). See [CONTRIBUTING.md — Code Generation Lineage](CONTRIBUTING.md#code-generation-lineage).
8+
9+
## Generation Drift
10+
11+
When a drift CI check fails, download the generated artifacts and compare. See [CONTRIBUTING.md — Debugging Generation Drift Failures](CONTRIBUTING.md#debugging-generation-drift-failures).
12+
13+
Do not guess or iterate blindly. Download the artifact first.
14+
15+
## Files You Can Safely Edit
16+
17+
- `overlays/python_speakeasy.yaml` — Speakeasy overlay
18+
- `scripts/post_generate.py` — Post-generation patch script
19+
- `poe_tasks.toml` — Build task definitions
20+
- `.github/workflows/` — CI workflows
21+
- `.github/dependabot.yml` — Dependabot configuration
22+
- `.github/speakeasy/dummy-compose.yml` — Speakeasy CLI version pin
23+
- `.speakeasy/workflow.yaml` — Speakeasy workflow configuration
24+
- `gen.yaml` — Speakeasy generator configuration
25+
- `CONTRIBUTING.md`, `AGENTS.md`, `README.md` — Documentation
26+
27+
## Files You Must NOT Edit By Hand
28+
29+
- `src/airbyte_api/` — Generated by Speakeasy
30+
- `pyproject.toml` — Generated by Speakeasy (version managed by release drafter)
31+
- `py.typed` — Generated by Speakeasy
32+
33+
## Build Commands
34+
35+
```bash
36+
uvx --from=poethepoet poe generate-code # Generate SDK from spec
37+
uvx --from=poethepoet poe post-generate # Run post-generation patches
38+
uvx --from=poethepoet poe generate-full # Full pipeline
39+
uvx --from=poethepoet poe lint # Lint checks
40+
uvx --from=poethepoet poe fix # Auto-fix lint/format
41+
uvx --from=poethepoet poe test # Run tests
42+
uvx --from=poethepoet poe typecheck # Type checking
43+
```
44+
45+
## Regenerating the SDK
46+
47+
Use the `/generate` slash command on a PR, or trigger manually from [Actions > Generate SDK](https://github.com/airbytehq/airbyte-api-python-sdk/actions/workflows/generate-command.yml).
48+
49+
Do not attempt to run `speakeasy run` locally — the `SPEAKEASY_API_KEY` is only available in CI.

‎CONTRIBUTING.md‎

Lines changed: 133 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,144 @@
11
# Contributing to This Repository
22

3-
Thank you for your interest in contributing to this repository. Please note that this repository contains generated code. As such, we do not accept direct changes or pull requests. Instead, we encourage you to follow the guidelines below to report issues and suggest improvements.
3+
## Important: This is a Generated Codebase
44

5-
## How to Report Issues
5+
> **Note:** This repository contains predominantly generated code. We do not accept direct changes to generated files. Report issues on GitHub or submit fixes to the upstream OpenAPI spec in [airbyte-platform](https://github.com/airbytehq/airbyte-platform).
66
7-
If you encounter any bugs or have suggestions for improvements, please open an issue on GitHub. When reporting an issue, please provide as much detail as possible to help us reproduce the problem. This includes:
7+
## Code Generation Lineage
88

9-
- A clear and descriptive title
10-
- Steps to reproduce the issue
11-
- Expected and actual behavior
12-
- Any relevant logs, screenshots, or error messages
13-
- Information about your environment (e.g., operating system, software versions)
14-
- For example can be collected using the `npx envinfo` command from your terminal if you have Node.js installed
9+
The Python SDK is generated through a multi-step pipeline:
10+
11+
```
12+
┌──────────────────────────────────────────┐
13+
│ 1. Upstream OpenAPI Spec │
14+
│ (airbyte-platform / api_sdk.yaml) │
15+
└──────────────────┬───────────────────────┘
16+
│
17+
▼
18+
┌──────────────────────────────────────────┐
19+
│ 2. Speakeasy Overlay (optional) │
20+
│ (overlays/python_speakeasy.yaml) │
21+
└──────────────────┬───────────────────────┘
22+
│
23+
▼
24+
┌──────────────────────────────────────────┐
25+
│ 3. Speakeasy Code Generation │
26+
│ (src/airbyte_api/) │
27+
└──────────────────┬───────────────────────┘
28+
│
29+
▼
30+
┌──────────────────────────────────────────┐
31+
│ 4. Post-Generation Patches │
32+
│ (scripts/post_generate.py) │
33+
└──────────────────┬───────────────────────┘
34+
│
35+
▼
36+
┌──────────────────────────────────────────┐
37+
│ 5. Package Build & Publish │
38+
│ (pyproject.toml → PyPI) │
39+
└──────────────────────────────────────────┘
40+
```
41+
42+
### Step-by-step details
43+
44+
1. **Upstream OpenAPI Spec** — The source-of-truth API definition lives in `airbyte-platform`:
45+
[`airbyte-api/server-api/src/main/openapi/api_sdk.yaml`](https://github.com/airbytehq/airbyte-platform/blob/main/airbyte-api/server-api/src/main/openapi/api_sdk.yaml)
46+
47+
2. **Speakeasy Overlay** — Python SDK-specific customizations applied on top of the upstream spec before code generation (currently a no-op placeholder):
48+
[`overlays/python_speakeasy.yaml`](https://github.com/airbytehq/airbyte-api-python-sdk/blob/main/overlays/python_speakeasy.yaml)
49+
50+
3. **Speakeasy Code Generation** — Speakeasy consumes the spec (+ overlay if enabled) and generates the Python SDK in `src/airbyte_api/`. These files should never be edited by hand.
51+
52+
4. **Post-Generation Patches** — A Python script applies any SDK-specific patches after generation (currently a no-op placeholder):
53+
[`scripts/post_generate.py`](https://github.com/airbytehq/airbyte-api-python-sdk/blob/main/scripts/post_generate.py)
54+
55+
5. **Package Build & Publish** — The generated SDK is built with `uv build` and published to PyPI via OIDC trusted publishing.
56+
57+
> **Tip:** If you need to change SDK behavior, determine which layer is appropriate:
58+
> - **API changes** → submit to the [upstream OpenAPI spec](https://github.com/airbytehq/airbyte-platform/blob/main/airbyte-api/server-api/src/main/openapi/api_sdk.yaml)
59+
> - **Python SDK-specific schema tweaks** → modify the [overlay](https://github.com/airbytehq/airbyte-api-python-sdk/blob/main/overlays/python_speakeasy.yaml)
60+
> - **Post-generation fixes** → modify the [post-generate script](https://github.com/airbytehq/airbyte-api-python-sdk/blob/main/scripts/post_generate.py)
61+
> - Then trigger regeneration (see below)
62+
63+
## For Maintainers
64+
65+
### Regenerating the SDK
66+
67+
Use the GitHub Actions workflow: [Actions > Generate SDK](https://github.com/airbytehq/airbyte-api-python-sdk/actions/workflows/generate-command.yml) > Run workflow
68+
69+
Or comment `/generate` on any PR to regenerate and push results to the PR branch.
70+
71+
### Release Process
72+
73+
Releases use a draft-based workflow:
74+
75+
1. The `release-drafter.yml` workflow runs on every push to main, creating/updating a draft release
76+
2. Review the draft at [Releases](https://github.com/airbytehq/airbyte-api-python-sdk/releases)
77+
3. Edit the draft version if needed
78+
4. Click "Publish release" — this triggers PyPI publication via OIDC
1579

16-
## Issue Triage and Upstream Fixes
80+
### Pre-Release Process
1781

18-
We will review and triage issues as quickly as possible. Our goal is to address bugs and incorporate improvements in the upstream source code. Fixes will be included in the next generation of the generated code.
82+
Pre-releases let you publish an SDK version for testing without making it the default on PyPI.
1983

20-
## Contact
84+
**Two ways to trigger a pre-release:**
2185

22-
If you have any questions or need further assistance, please feel free to reach out by opening an issue.
86+
1. **Slash command on a PR** (recommended for PR-based work):
87+
```
88+
/pre-release version=1.0.0rc1
89+
```
90+
This builds from the PR's head branch.
2391

24-
Thank you for your understanding and cooperation!
92+
2. **Manual workflow dispatch** (from the [Actions tab](https://github.com/airbytehq/airbyte-api-python-sdk/actions/workflows/pre-release-command.yml)):
93+
- **version** (required): e.g. `1.0.0rc1`, `1.0.0a1`. Must be valid PEP 440 with a pre-release suffix.
94+
- **ref** (optional, default: `main`): branch, tag, or commit SHA to build from.
2595

26-
The Maintainers
96+
**Using a pre-release:**
97+
98+
```bash
99+
pip install airbyte-api==1.0.0rc1
100+
```
101+
102+
### Debugging Generation Drift Failures
103+
104+
When the zero-diff CI check fails, it means the committed code doesn't match what the generation pipeline produces. To debug:
105+
106+
1. Download the generated artifacts from the failed CI run:
107+
```bash
108+
gh run download <RUN_ID> --name generated_sdk_code --dir /tmp/generated_from_ci
109+
```
110+
111+
2. Compare against committed code:
112+
```bash
113+
diff -rq src/ /tmp/generated_from_ci/src/
114+
```
115+
116+
3. Fix the root cause at the appropriate layer (overlay, post-generate script, or upstream spec), then comment `/generate` on the PR.
117+
118+
## Speakeasy CLI Version
119+
120+
The Speakeasy CLI version is pinned in [`.github/speakeasy/dummy-compose.yml`](https://github.com/airbytehq/airbyte-api-python-sdk/blob/main/.github/speakeasy/dummy-compose.yml) and bumped by Dependabot's `docker-compose` ecosystem. The `.speakeasy/workflow.yaml` uses `speakeasyVersion: pinned` to consume whatever version is installed.
121+
122+
## Build Tasks
123+
124+
Build tasks are defined in [`poe_tasks.toml`](https://github.com/airbytehq/airbyte-api-python-sdk/blob/main/poe_tasks.toml) and run via [poethepoet](https://poethepoet.natn.io/):
125+
126+
```bash
127+
uvx --from=poethepoet poe generate-code # Generate SDK from spec
128+
uvx --from=poethepoet poe post-generate # Run post-generation patches
129+
uvx --from=poethepoet poe generate-full # Full pipeline (generate + patches)
130+
uvx --from=poethepoet poe lint # Run linting checks
131+
uvx --from=poethepoet poe fix # Auto-fix lint/formatting
132+
uvx --from=poethepoet poe test # Run tests
133+
uvx --from=poethepoet poe typecheck # Run type checking
134+
```
135+
136+
## How to Report Issues
137+
138+
If you encounter bugs or have suggestions, please [open an issue](https://github.com/airbytehq/airbyte-api-python-sdk/issues/new). Include:
139+
140+
- A clear and descriptive title
141+
- Steps to reproduce the issue
142+
- Expected and actual behavior
143+
- Any relevant logs or error messages
144+
- SDK version and Python version

0 commit comments

Comments
 (0)