From fcbc439e5b9a171d564cdea9825bdb5d7a2e0224 Mon Sep 17 00:00:00 2001
From: moonyue-w <300878504+moonyue-w@users.noreply.github.com>
Date: Tue, 22 Sep 2026 20:02:48 +0800
Subject: [PATCH] docs: add contribution workflow

---
 .github/CODEOWNERS               |  1 +
 .github/pull_request_template.md | 35 ++++++++++++++++++++
 CONTRIBUTING.md                  | 57 ++++++++++++++++++++++++++++++++
 3 files changed, 93 insertions(+)
 create mode 100644 .github/CODEOWNERS
 create mode 100644 .github/pull_request_template.md
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 0000000..f293a66
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1 @@
+* @moonyue-w
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..8a0e372
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,35 @@
+## Summary
+
+<!-- What changed? -->
+
+## Why
+
+<!-- Why is this change needed? -->
+
+## Verification
+
+- [ ] `make lint`
+- [ ] `make build`
+- [ ] `make test`
+- [ ] `make docs-check`
+- [ ] `go build ./examples/...`
+- [ ] Account-backed integration tests run, or not required
+
+Commands and results:
+
+```text
+
+```
+
+## Impact
+
+- [ ] Public API or behavior changed
+- [ ] Generated API documentation updated
+- [ ] Forward/Managed contract fixtures updated
+- [ ] Python and TypeScript parity considered
+- [ ] Migration notes added for a breaking change
+- [ ] No credentials, `.env.live`, logs, or generated test output committed
+
+Additional context:
+
+<!-- Link related issues/PRs and explain any unchecked item. -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..f12a6da
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,57 @@
+# Contributing
+
+Thank you for contributing to the Qoder Cloud Agents Go SDK.
+
+## Development workflow
+
+1. Create a focused branch from the latest `main`.
+2. Keep each pull request limited to one independently reviewable change.
+3. Use Conventional Commits, for example `fix(forward): preserve request id`.
+4. Open a pull request and wait for all required checks before merging.
+
+GitHub `main` is the source of truth. Do not develop against or copy changes from the internal CI mirror.
+
+## Setup and checks
+
+Use Go 1.23 or newer.
+
+```bash
+go mod download
+make lint
+make build
+make test
+make docs-check
+go build ./examples/...
+```
+
+`make test` runs the offline unit and contract suites. It must not require network access or credentials.
+
+## Test layers
+
+- **Unit tests** cover transport, errors, pagination, streaming, serialization, credentials, and helpers. Run `make test-unit`.
+- **Contract tests** verify HTTP methods, paths, headers, request bodies, and response decoding with local transports. Run `make test-contract`.
+- **Integration tests** exercise account-backed resource lifecycles. Copy `.env.live.example` to `.env.live`, use a dedicated test account, then run `make test-live-all`.
+- **E2E tests** execute real models and tools. They additionally require the documented model and execution gates, then run with `make test-e2e`.
+- **Examples** are runnable documentation. Tests must not import helpers from `examples/`; verify examples with `go build ./examples/...`.
+
+Never commit `.env.live`, tokens, credentials, generated logs, or test output. Live tests must register cleanup immediately after creating a resource.
+
+## API and contract changes
+
+When adding or changing an endpoint:
+
+1. Update the relevant `forward/` or `managed/` implementation and public types.
+2. Update the applicable fixtures under `forward/testdata/` or `managed/testdata/`.
+3. Add focused unit and contract coverage, including failure behavior.
+4. Regenerate API documentation with `make docs` and verify it with `make docs-check`.
+5. Call out the corresponding Python and TypeScript work in the pull request, or explain why the change is language-specific.
+
+The fixtures are maintained manually. A passing fixture test proves consistency with this repository, not automatically with service routes or the other SDKs.
+
+## Compatibility conventions
+
+The SDK intentionally keeps Qoder-branded `X-Qoder-*` metadata headers and resumable session-event streams. Preserve those extensions unless the change explicitly revises the public contract. Breaking public API changes require a minor-version release while the SDK remains pre-1.0 and must include migration notes.
+
+## Pull requests
+
+Complete the pull request template, include exact verification commands and results, and identify public API, documentation, integration-test, and cross-SDK effects. Do not combine unrelated refactors with behavior changes.