From b763cca3c98f848dc240040b2696e3c3c596253a Mon Sep 17 00:00:00 2001 From: Brandon High <759848+highb@users.noreply.github.com> Date: Thu, 30 Apr 2026 16:51:40 -0700 Subject: [PATCH] =?UTF-8?q?Add=20v1=E2=86=92v2=20migration=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In preparation for the v2.0.0-alpha.1 cut (PR #109), add the user-facing migration documentation: - **MIGRATING.md** — hand-written v1 → v2 upgrade guide covering the module path break (the biggest one — `import .../conductorone-sdk-go` → `.../v2`), the IGA-1181 schema renames (AccessConflictNotificationConfig, AutomationsTaskAction, PolicyForm, V2 service splits), and the new API surfaces accumulated since v1.27.x (paper-secret, role-mining, principal, workload-federation, A2UI). Some sections are placeholders to be populated when the v2.0.0-alpha.1 regen PR's full breaking-change list is available. - **.genignore** entries for `MIGRATING.md` and `CHANGELOG.md` so Speakeasy never overwrites the hand-written guides on regen. --- .genignore | 4 ++- MIGRATING.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 MIGRATING.md diff --git a/.genignore b/.genignore index 763d0d4be..26359e779 100644 --- a/.genignore +++ b/.genignore @@ -10,4 +10,6 @@ uhttp/ go.mod go.sum USAGE.md -RELEASES.md \ No newline at end of file +RELEASES.md +MIGRATING.md +CHANGELOG.md \ No newline at end of file diff --git a/MIGRATING.md b/MIGRATING.md new file mode 100644 index 000000000..f18db9090 --- /dev/null +++ b/MIGRATING.md @@ -0,0 +1,93 @@ +# Migrating from v1 to v2 + +This guide covers the breaking changes between `conductorone-sdk-go` v1.x and v2.0.0. + +The v2.0.0 line was cut to absorb the spec drift accumulated since v1.27.x — specifically the [IGA-1181](https://linear.app/ductone/issue/IGA-1181) collision-fix renames plus six weeks of API additions. The v2.0.0-alpha.1 release is the first prerelease in this line; it is **not yet GA**. + +## 1. Module path break + +Per [Go's semantic import versioning rules](https://research.swtch.com/vgo-import), v2.0.0 changes the import path: + +```diff +- import "github.com/conductorone/conductorone-sdk-go" ++ import "github.com/conductorone/conductorone-sdk-go/v2" +``` + +Update `go.mod`: + +```bash +go get github.com/conductorone/conductorone-sdk-go/v2@v2.0.0-alpha.1 +go mod tidy +``` + +A simple `gofmt`-friendly find-and-replace covers most cases: + +```bash +find . -name '*.go' -not -path './vendor/*' \ + -exec sed -i.bak 's|github.com/conductorone/conductorone-sdk-go/|github.com/conductorone/conductorone-sdk-go/v2/|g' {} + +find . -name '*.go.bak' -delete +goimports -w . +``` + +The v1 module remains available at the unsuffixed path; v1 and v2 can coexist in the same binary if needed during a phased migration. + +## 2. Renamed types (IGA-1181 collision fixes) + +Several types were renamed to disambiguate cross-package collisions in the OpenAPI spec. The old names existed in v1; the new names are required in v2. + +> _Populated from the v2.0.0-alpha.1 regen PR's `**Breaking ⚠️**` list. The placeholders below will be filled in once that PR lands._ + +### Service splits + +Two operations now have separate v1 and v2 service types because the API exposes both endpoints: + +| v1 type | v2 type for v1 endpoint | v2 type for v2 endpoint | +|---|---|---| +| `AppOwners.Set` | `AppOwners.Set` (unchanged) | `AppOwnersV2.Set` (new) | +| `AppEntitlementOwners.Set` | `AppEntitlementOwners.Set` (unchanged) | `AppEntitlementOwnersV2.Set` (new) | + +Pick the version that matches the API endpoint your code targets. v1 endpoints continue to work; v2 endpoints have additional capabilities (entitlement-scoped owners, etc.). + +### Schema renames + +| v1 | v2 | +|---|---| +| `NotificationConfig` (in access_conflict context) | `AccessConflictNotificationConfig` | +| `NotificationConfig` (in access_review context) | `AccessReviewNotificationConfig` | +| `TaskAction` | `AutomationsTaskAction` | +| `Webhook` (in automations context) | `AutomationsWebhook` | +| `Form` (in policy step context) | `PolicyForm` | + +### Field-level changes + +> _To be populated from the regen PR. Likely candidates: `TaskView` shape changes across all `TaskActions.*` and `Task.*` operations, `AccessReview` create/update/get/list response shape changes, `AccessReviewTemplate` similar._ + +## 3. New services and fields (non-breaking, but newly available) + +Six weeks of c1 spec additions are now available in v2: + +- **Paper Secret** — `PaperSecret`, `PaperSecretAdmin` services for vault-backed secret sharing. +- **Role Mining Management** — `RoleMiningManagement`, `RoleMiningManagementSearch` for surfaced role suggestions. +- **Principal / Credentials** — `Principal` service with credential CRUD + revocation. +- **Workload Federation** — `WorkloadFederation` (trusts, providers, CEL testing) for non-human identity flows. +- **A2UI** — `A2UI` (surfaces, feedback, actions) for Agent-to-UI integrations. +- **Automations expansion** — additional automation triggers and steps (`schedule_trigger_no_user`, `webhook_listener_auth_capability_url`, etc.). +- **Webhook callback timeout** — `Webhook.callback_timeout` now configurable. +- **Other fields**: `connector_api_version`, `directory_merge_config`, `provisioner_assignment` on entitlement provision policies, `origin` on owners/users, etc. + +These are additive and do not require code changes to existing v1 code beyond the import path bump in §1. + +## 4. Workflow / CI + +If your CI fetches the SDK at a pinned version, update accordingly: + +```bash +# replace pinned version +go get github.com/conductorone/conductorone-sdk-go/v2@v2.0.0-alpha.1 +``` + +If you use Dependabot / Renovate, both will detect the new module path as a separate package — you may need to add a config rule pairing v1 → v2 to track upgrades. + +## 5. Reporting issues + +Issues with v2.0.0-alpha.1 should reference the alpha tag explicitly. File them at https://github.com/ConductorOne/conductorone-sdk-go/issues. The IGA team owns the SDK and TF provider — see the [Terraform Linear project](https://linear.app/ductone/project/423a706e-1c8d-4283-b1e6-43f082f53826) for active work.