@postman/sdk-config 0.0.0 → 0.0.2

package/README.md

@@ -1,9 +1,139 @@
 # @postman/sdk-config
 
-Namespace placeholder for `@postman/sdk-config`.
+Shared, runtime-validated configuration contracts for Postman's SDK generation pipeline.
 
-Real releases ship from CI via OIDC Trusted Publishing — see the linked
-repository for the release workflow. This `0.0.0` stub exists only to claim
-the name under the `@postman` scope and apply least-privilege team
-permissions. It is private (`--access restricted`); the first real release
-makes the package public if/when the team decides.
+This package is the source of truth for `SdkConfigIr`. It is intended for sdk-gen-core,
+sdk-gen-api, Postman and Fern CLIs, and translators that normalize producer-specific configuration
+before generation.
+
+## Install
+
+The package is configured as a restricted package in the `@postman` npm scope.
+
+```sh
+npm install @postman/sdk-config
+```
+
+## Use
+
+Prefer the versioned entry point at transport and persistence boundaries:
+
+```ts
+import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-config-ir/v1';
+
+const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);
+```
+
+The package also exposes `@postman/sdk-config` and `@postman/sdk-config/sdk-config-ir` as convenient
+current-version entry points. Persisted payloads must still include `schemaVersion`.
+
+Both ESM `import` and CommonJS `require` consumers are supported.
+
+## Project layout
+
+```text
+src/
+  sdk-config-ir/
+    v1/                 # Versioned schema, inferred types, and contract reference
+tests/
+  fixtures/
+    sdk-config-ir/v1/   # Canonical portable payloads
+  sdk-config-ir/v1/     # Contract behavior tests
+docs/
+  migration.md          # sdk-gen-core adoption sequence
+```
+
+## Develop
+
+Requires Node.js 24 or newer. If you use nvm, run `nvm use` from the repository root.
+
+```sh
+npm install
+npm run check
+npm pack --dry-run
+```
+
+`npm run check` verifies formatting, linting, TypeScript, tests, and the dual-format package build.
+
+## Versioning and publishing
+
+- npm access is `restricted`; do not set package.json `private: true`, because npm would refuse to
+  publish it.
+- Additive v1 fields require a package minor version and a consumer-first rollout because v1 uses
+  strict runtime objects: an older consumer rejects fields it does not know.
+- Breaking wire changes get a new schema directory and discriminator such as `sdk-config-ir/v2`.
+- Keep the previous version exported while consumers migrate.
+
+### Manual release process
+
+Release automation is intentionally deferred while the tagging and publishing process is reviewed
+with Postman's security team. Until that process is established, use the following manual release
+procedure. The commands use `1.1.0` as an example; replace it consistently with the version being
+released.
+
+#### 1. Prepare a release branch from develop
+
+Normal feature pull requests target `develop`. Start the release from an up-to-date `develop`
+branch, update the version without creating a tag, and run the complete check suite:
+
+```sh
+git switch develop
+git pull --ff-only origin develop
+git switch -c release/v1.1.0
+npm version 1.1.0 --no-git-tag-version
+npm run check
+git add package.json package-lock.json
+git commit -m "release: v1.1.0"
+git push -u origin release/v1.1.0
+```
+
+Open a pull request from `release/v1.1.0` into `main`. Review the version change, wait for required
+checks and approvals, and merge it. The release branch isolates the version bump and preserves the
+exact `develop` snapshot being reviewed, while work can continue independently on `develop`.
+
+#### 2. Merge main back into develop
+
+The publishing workflow requires the tagged commit to be in the history of the repository's default
+branch, `develop`. After the release pull request is merged, create a synchronization branch from
+the latest `develop` and merge the released `main` into it:
+
+```sh
+git fetch origin
+git switch -c chore/merge-main-after-v1.1.0 origin/develop
+git merge --no-ff origin/main -m "Merge main back to develop after v1.1.0"
+git push -u origin chore/merge-main-after-v1.1.0
+```
+
+Open a pull request from `chore/merge-main-after-v1.1.0` into `develop`, wait for its checks, and use
+**Create a merge commit** to merge it. Do not squash or rebase this pull request: the original
+`main` commit must remain in `develop`'s ancestry for the publishing workflow's validation. The
+temporary branch can then be deleted safely.
+
+#### 3. Create the release tag from main
+
+After the synchronization pull request is merged, update your local `main` and verify that
+`package.json` contains the version you are about to tag:
+
+```sh
+git switch main
+git pull --ff-only origin main
+node -p "require('./package.json').version"
+```
+
+Create a signed, annotated tag on the checked-out `main` commit, verify it locally, and push it:
+
+```sh
+git tag -s v1.1.0 -m "Release v1.1.0"
+git tag -v v1.1.0
+git push origin v1.1.0
+```
+
+Pushing a tag matching `v*.*.*` automatically triggers the **Package Release** workflow defined in
+`.github/workflows/npm-publish.yml`. In GitHub, open **Actions** → **Package Release** and confirm
+the tag-triggered run succeeds.
+
+If publishing fails after the tag has been created, do not delete, move, or recreate the tag. After
+the underlying problem is fixed, open **Actions** → **Package Release** → **Run workflow** and enter
+the existing tag, such as `v1.1.0`, to retry it.
+
+See the [SDK Config IR v1 reference](src/sdk-config-ir/v1/README.md) for the complete contract.