Prep 0.1.0 release: docs, drift pins, and CI hygiene (#30)

* Rewrite 0.1.0 changelog entry to reflect actual public API

The placeholder entry described features at a high level and predated
the final API surface. Replace it with bullets that match what 0.1.0
actually ships: the exported helpers, exception hierarchy, retry
behavior, extension API, and supported Python versions. Bumps the
release date to 2026-04-28.

* Rewrite README for the 0.1.0 release

Replaces the prior README with a from-scratch rewrite tailored to an
autogenerated Python SDK against a versioned REST API. Structured per
the conventions of openai-python, cloudflare-python, kubernetes-client,
qiskit, and cirq: tagline, badges, codegen disclosure, alternative
high-level SDKs, install, quickstart (Bell circuit), auth, async,
errors, retries, pagination, polling, sessions, advanced (hooks /
custom transport / error mapping / native gates), SDK-vs-API version
table, SemVer carve-outs, requirements, contributing, support, license.

* Rename code owners to developer-tools and link CUDA-Q backend source

CODEOWNERS now points at @ionq/developer-tools, matching the team's
current name. The README's CUDA-Q bullet now links directly to the
IonQServerHelper backend in NVIDIA/cuda-quantum so users can see how
the integration is wired.

* Rewrite CONTRIBUTING.md for the 0.1.0 release

Replaces the brief stub with a comprehensive contributor guide
tailored to a generated Python SDK. Sections cover code of conduct,
where to ask questions, bug reporting, scope guidance, the
generated-vs-hand-written code structure (with the table of paths,
the # @generated marker, and the PR-time staleness check), uv-based
development setup, local check commands, integration tests, the
exact regeneration command, the PR workflow, SemVer carve-outs,
release process, security disclosure, and the CLA contact.

* Strengthen issue templates and add security contact link

Add an affected-area dropdown that mirrors CONTRIBUTING.md's
generated/hand-written taxonomy, split bug description into what-happened
and expected-behavior, require the reproduction field, add a
search-confirmation checkbox to both templates, and route security reports
through SECURITY.md instead of public issues.

* Write SECURITY.md for the 0.1.0 release

* Deduplicate documentation across README, CONTRIBUTING, and templates

The generated/hand-written file boundary was restated in five places (README,
CONTRIBUTING table, PR template, bug-report dropdown, and pyproject exclusions)
with subtle drift, including __init__.py listed inconsistently. CONTRIBUTING.md
is now the single source of truth; the other surfaces link to it. The bug-area
classification keys off the @generated marker rather than enumerated paths so
new generated files don't require doc updates.

Other duplications removed:
- README "Requirements" section (duplicated pyproject.toml dep pins)
- One-row SDK<->API version table (kept the prose that was useful)
- Hard-coded "Python 3.12, 3.13, or 3.14" lists (canonical: pyproject + ci.yml)
- Standalone "Security" section in CONTRIBUTING (duplicated the Getting help bullet)
- @mjk personal handle for the CLA (now opensource@ionq.co)

Adds an [Unreleased] section to CHANGELOG so the contribution instruction to
"add to the next release section" works.

* Soft-wrap CONTRIBUTING.md and CODE_OF_CONDUCT.md

Replace hard-wrapped prose (~80 cols) with one-paragraph-per-line so future
edits don't reflow whole paragraphs. Word counts unchanged; rendered output
is identical.

* Tighten 0.1.0 docs and templates against peer-SDK conventions

- Rewrite README relative links as absolute GitHub URLs so they
  resolve on PyPI (the renderer does not follow relative paths).
- Add a Safe Harbor clause to SECURITY.md committing to no legal
  action against good-faith researchers.
- Add `[Unreleased]` / `[0.1.0]` link reference footers to CHANGELOG.md
  so the version tokens resolve.
- Replace the abbreviated CODE_OF_CONDUCT.md with the verbatim
  Contributor Covenant 2.1 and route reports to <conduct@ionq.co>;
  sync the same address in CONTRIBUTING.md.
- Make the "What did you expect?" field optional in the bug-report
  template - tracebacks usually make it redundant.

* Pin README copy to runtime constants and align doc drift

- Bump pre-commit ruff to v0.15.12 so it matches the dev dep.
- Drop "Quantum" from the README one-liner to align with pyproject
  and the auto-generated package docstring.
- Match LoggingHook arrow style between README and extensions.py.
- Reword CONTRIBUTING.md to describe the ty config accurately
  (rule override for api/ + models/, not a path exclusion).
- Fill in 1.5x growth and default total wait in the polling
  module docstring.
- Extract _DEFAULT_BASE_URL so the integration test can import the
  production URL once instead of redeclaring it.
- Decouple unit-test placeholder URLs from the production base.
- Add tests/test_docs_consistency.py to pin README copy to the
  retry, timeout, and polling constants so future drift fails CI.

* Pin more drift surfaces in CI and dedupe workflow setup

Extends the docs-consistency gate to cover the retry backoff trio,
default base URL, auth prefix, exception classes, Python floor across
pyproject/CI/.python-version/ruff/ty, generated-paths exclusions, the
SessionManager example backend, and the package description across
pyproject/README/__init__.py/template. Adds a setup-uv composite action
so the pinned SHA and Python default live in one file; routes all five
setup-using workflows through it. Names polling's growth factor, hoists
the test BASE_URL into conftest, switches the SPDX post-hook to stamp
\$(date +%Y), and unifies the package description on "A client library
for accessing IonQ Cloud Platform API".

* Drop redundant template-level description pin

The template's only output is ionq_core/__init__.py, which CI
regenerates and then asserts against the canonical text via
test_init_module_docstring. A separate template-content test was
redundant - the output check catches the same drift. Also trim a
parenthetical from the bug-reporting copy.

* Pin remaining drift surfaces and decouple tests from /v0.4

Add eight new test classes to test_docs_consistency.py covering generator
tool versions, ClientExtension docstring defaults, polling docstring
constants, polling.__all__ in README, pyproject classifiers vs CI matrix,
_DEFAULT_BASE_URL vs openapi.json servers[0].url, SPDX year consistency
across hand-written and generated files, and resolution of cross-doc
anchor links. Pin spec-drift.yml's curl URL to _DEFAULT_BASE_URL so a
future v0.4 -> v0.5 bump can't silently keep curl'ing the stale endpoint.

Derive the API path in tests/conftest.py and tests/test_session.py from
_DEFAULT_BASE_URL via urlparse instead of hardcoding /v0.4.

* Simplify doc-drift tests and tighten surrounding copy

Flatten tests/test_docs_consistency.py from 13 classes to module-level
parametrized tests; same coverage in 217 lines instead of 291. Drop the
markdown-anchor resolver test (GitHub already renders broken anchors
visibly) and the backoff_factor pin (numbers live in _transport.py and
won't drift independently of the README).

Merge README's "SDK version vs API spec version" into "Versioning" -
the SemVer carve-outs already imply API/SDK independence. Drop the
duplicated higher-level-interface paragraph from CONTRIBUTING (already
linked in "Getting help"). Tighten the post-generation hook paragraph
to a one-liner; the config file is right above.

Collapse the three-line max_retries fallback ladder in IonQClient into
a single next() expression.

* Cut documentation duplication and drift surfaces

Trim README, CONTRIBUTING, and SECURITY to single-source content; drop
the README pin tests for the removed copy. Module docstrings (rendered
into the published API reference) now own behavioral detail; the README
is the entry point only.

- README: drop Authentication detail, Async usage, exception ASCII tree,
  retry/timeout values, full pagination/polling/sessions snippets, the
  Advanced section, and versioning carve-outs - all duplicated in module
  docstrings or drift-prone constants.
- CONTRIBUTING: drop the hand-maintained generated-file list (now
  .gitattributes is the single source), the Versioning section
  (duplicate of README), and the Releasing section (maintainer-only).
- SECURITY: drop the Supported Versions table - it would lie the moment
  0.2 ships; the prose policy above already covers it.
- test_docs_consistency: drop test_readme_mentions_runtime_constant,
  test_readme_lists_exception_class, test_readme_lists_polling_name, and
  the README half of the session-backend pin. Internal-consistency
  checks (Python floor, classifiers, ruff/coverage/.gitattributes
  paths, generated-tool versions, base URL, SPDX year, ClientExtension
  and polling docstring pins) are unchanged.

* Fix SPDX post-hook silently skipped by openapi-python-client

openapi-python-client checks `cmd.split(" ")[0]` against PATH before
running each post_hook. The `YEAR=$(date +%Y) perl ...` prefix made the
"command" `YEAR=$(date`, which fails the `shutil.which` check; the hook
was skipped, regeneration dropped SPDX headers, and CI's staleness gate
fired. Move the year computation into Perl's BEGIN block so the leading
token is `perl` and the env-prefix trick is no longer needed.

* Drop BEGIN wrapper from SPDX post-hook year computation

(localtime)[5]+1900 is the canonical short form; with -p the wrapper's
once-per-run benefit is moot (one assignment per file, microseconds).

* Address review feedback on 0.1.0 prep

- Switch SPDX post-hook from localtime to gmtime so the stamped year
  is deterministic across CI runner timezones.
- Drop the leading underscore on _DEFAULT_BASE_URL and _DEFAULT_TIMEOUT
  in ionq_client.py; both are load-bearing for the drift-pin tests
  (and tests/conftest.py), so the private-by-convention naming was
  misleading. Not added to __all__ - kept off the wildcard surface.
- Retarget dead CONTRIBUTING.md#reporting-bugs and #code-structure
  links in bug_report.yml and pull_request_template.md to the existing
  #proposing-changes heading; drop the redundant reporting-guide link
  since the template fields already prompt for what to include.
- Add .github/actions/** to zizmor.yml path filters so the new
  setup-uv composite action gets the same audit coverage as workflow
  files.

* Generalize SessionManager backend regex and unquote enable-cache

Tighten test_session_example_backend_consistent so a non-qpu example
backend (e.g. "simulator") in session.py would still be caught; pass
enable-cache to the composite setup-uv action as a YAML boolean
instead of a quoted string.

* Unwrap hard-wrapped prose in docs and issue templates

* Bump 0.1.0 release date to open-source launch

* Correct 0.1.0 release date to actual launch day

Author: splch

.github/CODEOWNERS

@@ -1,3 +1,2 @@
 # Default owners for everything in the repo.
-* @ionq/sdk-team
-
+* @ionq/developer-tools

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -3,20 +3,49 @@ description: Report a bug in ionq-core
 labels: [bug]
 
 body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report. Please search [existing issues](https://github.com/ionq/ionq-core-python/issues) first.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      description: |
+        See [proposing changes](https://github.com/ionq/ionq-core-python/blob/main/CONTRIBUTING.md#proposing-changes) for the boundary between generated and hand-written code.
+      options:
+        - Generated client (regenerated from OpenAPI spec)
+        - Hand-written extensions (retry, pagination, polling, sessions, native gates, etc.)
+        - API surface / OpenAPI spec (originates upstream)
+        - Documentation
+        - Tests or tooling
+        - Not sure
+    validations:
+      required: true
+
   - type: textarea
-    id: description
+    id: what-happened
     attributes:
-      label: Description
-      description: What happened, and what did you expect to happen?
+      label: What happened?
+      description: A clear description of the bug, including any error message or traceback.
     validations:
       required: true
 
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect to happen?
+      description: Optional - skip if a traceback or error message above already shows the problem.
+
   - type: textarea
     id: reproduction
     attributes:
       label: Reproduction
       description: Minimal code or steps to reproduce the bug.
       render: Python
+    validations:
+      required: true
 
   - type: textarea
     id: version
@@ -25,8 +54,16 @@ body:
       description: |
         Paste the output of:
         ```bash
-        python -c "import ionq_core; print(ionq_core.__version__); import platform; print(platform.python_version()); print(platform.platform())"
+        python -c "import ionq_core, sys, platform; print(ionq_core.__version__, sys.version, platform.platform())"
         ```
       render: Text
     validations:
       required: true
+
+  - type: checkboxes
+    id: searched
+    attributes:
+      label: Pre-submit checks
+      options:
+        - label: I searched existing issues and didn't find a duplicate.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/ionq/ionq-core-python/security/policy
+    about: Email security@ionq.co. Do not open a public issue.
   - name: IonQ Support
     url: https://ionq.com/contact
     about: For account, billing, or platform questions, contact IonQ support directly.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -3,10 +3,23 @@ description: Suggest a feature for ionq-core
 labels: [enhancement]
 
 body:
+  - type: markdown
+    attributes:
+      value: |
+        Please search [existing issues](https://github.com/ionq/ionq-core-python/issues) before opening a new request. For API surface changes (new endpoints, parameter names, response shapes), see [proposing changes](https://github.com/ionq/ionq-core-python/blob/main/CONTRIBUTING.md#proposing-changes).
+
   - type: textarea
     id: description
     attributes:
       label: Description
       description: What problem would this solve, and how would you like it to work?
     validations:
       required: true
+
+  - type: checkboxes
+    id: searched
+    attributes:
+      label: Pre-submit checks
+      options:
+        - label: I searched existing issues and didn't find a duplicate.
+          required: true

.github/actions/setup-uv/action.yml

@@ -0,0 +1,20 @@
+name: Set up uv with Python
+description: Install uv and Python with the project's pinned defaults.
+
+inputs:
+  python-version:
+    description: Python version to install. Defaults to the project's floor.
+    required: false
+    default: "3.12"
+  enable-cache:
+    description: Pass-through to astral-sh/setup-uv enable-cache.
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: ${{ inputs.enable-cache }}

.github/pull_request_template.md

@@ -9,6 +9,5 @@
 ---
 
 > [!IMPORTANT]
-> Most code in `ionq_core/` is auto-generated. Do not edit files under `ionq_core/api/`,
-> `ionq_core/models/`, or `ionq_core/client.py`, `errors.py`, `types.py` directly.
-> See [CONTRIBUTING.md](../CONTRIBUTING.md#code-structure) for details.
+> Most code in `ionq_core/` is auto-generated and overwritten on regeneration.
+> See [CONTRIBUTING.md](../CONTRIBUTING.md#proposing-changes) for which files are safe to edit.

.github/workflows/ci.yml

@@ -23,9 +23,8 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - uses: ./.github/actions/setup-uv
         with:
-          python-version: "3.12"
           enable-cache: ${{ github.event_name == 'push' }}
       - run: uv sync
       - run: uv run ruff check
@@ -43,7 +42,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - uses: ./.github/actions/setup-uv
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: ${{ github.event_name == 'push' }}
@@ -57,8 +56,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - uses: ./.github/actions/setup-uv
         with:
-          python-version: "3.12"
           enable-cache: ${{ github.event_name == 'push' }}
       - run: uvx pip-audit --require-hashes --strict -r <(uv pip compile pyproject.toml --generate-hashes)

.github/workflows/docs.yml

@@ -19,9 +19,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
-        with:
-          python-version: "3.12"
+      - uses: ./.github/actions/setup-uv
       - run: uv sync
       - run: uv run pdoc -o docs/ -d google ionq_core
       - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5

.github/workflows/generated.yml

@@ -18,10 +18,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
-        with:
-          python-version: "3.12"
-          enable-cache: false
+      - uses: ./.github/actions/setup-uv
       - name: Prepare spec
         run: |
           set -euo pipefail

.github/workflows/integration.yml

@@ -24,9 +24,8 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - uses: ./.github/actions/setup-uv
         with:
-          python-version: "3.12"
           enable-cache: true
       - run: uv sync
       - name: Run integration tests