From c3c133b2748b906357652e05d04dd488921925ac Mon Sep 17 00:00:00 2001 From: Steven Zhang Date: Wed, 12 Nov 2025 16:00:07 -0600 Subject: [PATCH 1/2] ci: adding pre-release ci for oxygen sdk --- .github/workflows/manual-publish-docs.yml | 1 + .github/workflows/manual-publish.yml | 1 + .github/workflows/shopify-oxygen.yml | 28 ++++++++ .release-please-manifest.json | 3 +- CONTRIBUTING.md | 2 +- .../publishing-pre-release-modules.md | 71 +++++++++++++++++++ packages/sdk/shopify-oxygen/tsconfig.ref.json | 7 +- packages/sdk/shopify-oxygen/typedoc.json | 5 ++ release-please-config.json | 8 +++ tsconfig.json | 3 + 10 files changed, 122 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/shopify-oxygen.yml create mode 100644 contributing/publishing-pre-release-modules.md create mode 100644 packages/sdk/shopify-oxygen/typedoc.json diff --git a/.github/workflows/manual-publish-docs.yml b/.github/workflows/manual-publish-docs.yml index 12608d318f..e2b4cf375f 100644 --- a/.github/workflows/manual-publish-docs.yml +++ b/.github/workflows/manual-publish-docs.yml @@ -24,6 +24,7 @@ on: - packages/sdk/server-ai - packages/telemetry/browser-telemetry - packages/sdk/combined-browser + - packages/sdk/shopify-oxygen name: Publish Documentation jobs: build-publish: diff --git a/.github/workflows/manual-publish.yml b/.github/workflows/manual-publish.yml index 17771edb76..31d1206635 100644 --- a/.github/workflows/manual-publish.yml +++ b/.github/workflows/manual-publish.yml @@ -40,6 +40,7 @@ on: - packages/ai-providers/server-ai-langchain - packages/telemetry/browser-telemetry - packages/sdk/combined-browser + - packages/sdk/shopify-oxygen prerelease: description: 'Is this a prerelease. If so, then the latest tag will not be updated in npm.' type: boolean diff --git a/.github/workflows/shopify-oxygen.yml b/.github/workflows/shopify-oxygen.yml new file mode 100644 index 0000000000..385e5e6868 --- /dev/null +++ b/.github/workflows/shopify-oxygen.yml @@ -0,0 +1,28 @@ +name: sdk/shopify-oxygen + +on: + push: + branches: [main, 'feat/**'] + paths-ignore: + - '**.md' + pull_request: + branches: [main, 'feat/**'] + paths-ignore: + - '**.md' + +jobs: + build-test-shopify-oxygen: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + # https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started#requirements + node-version: lts/* + registry-url: 'https://registry.npmjs.org' + - id: shared + name: Shared CI Steps + uses: ./actions/ci + with: + workspace_name: '@launchdarkly/shopify-oxygen-sdk' + workspace_path: packages/sdk/shopify-oxygen diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 4953564675..1c2911aeda 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -21,5 +21,6 @@ "packages/store/node-server-sdk-redis": "4.2.14", "packages/telemetry/browser-telemetry": "1.0.11", "packages/telemetry/node-server-sdk-otel": "1.3.2", - "packages/tooling/jest": "0.1.12" + "packages/tooling/jest": "0.1.12", + "packages/sdk/shopify-oxygen": "0.0.0" } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fdf84e631f..4e539cf549 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -235,7 +235,7 @@ There are a number of categories of packages in the monorepo: 5. **Tooling packages** (red): Development and testing tools - Jest testing utilities -### Depenencies +### Dependencies In general dependencies should be avoided unless they are absolutely necessary. For each dependency several considerations should be made: diff --git a/contributing/publishing-pre-release-modules.md b/contributing/publishing-pre-release-modules.md new file mode 100644 index 0000000000..eeae8585bb --- /dev/null +++ b/contributing/publishing-pre-release-modules.md @@ -0,0 +1,71 @@ +# Creating pre-releases modules + +The following steps are to create a pre release modules which would walk through the initial +CI work needed for new SDKs. + +## 1. Extend `release-please-config.json` + +Add a record of your new SDK package to `packages` +``` +"PATH_TO_YOUR_PACKAGE": { + "prerelease": true, + "bump-minor-pre-major": true, + "release-as": "0.1.0" +} +``` +> NOTE: the `PATH_TO_YOUR_PACKAGE` needs to match the path in `package.json` +> eg `packages/sdk/server-node` + +This is the minimum changes you need to do. `bump-minor-pre-major` option means only +minor version will be incremented while your package is in pre-release state. +> Pre-release packages **MUST** be in major version `0` + +## 2. Add initial release manifest + +Add the following to `.release-please-manifest.json` +``` +"PATH_TO_YOUR_PACKAGE": "0.0.0" +``` + +## 3. Add option to manual workflows + +Add `PATH_TO_YOUR_PACKAGE` to the `on.workflow_dispatch.inputs.workspace_path.options` +array in the following files: +- [`manual-publish-docs.yml`](./workflows/manual-publish-docs.yml) +- [`manual-publish.yml`](./workflows/manual-publish.yml) + +## 4. Create a CI non-release workflow for just the project + +You will add a file in the `.github/workflows` directory that tells GHA (mostly) how to +test your SDK. Below is a simple template to get started: +``` +name: sdk/YOUR_SDK + +on: + push: + branches: [main, 'feat/**'] + paths-ignore: + - '**.md' + pull_request: + branches: [main, 'feat/**'] + paths-ignore: + - '**.md' + +jobs: + build-test-YOUR_SDK: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: lts/* + registry-url: 'https://registry.npmjs.org' + - id: shared + name: Shared CI Steps + uses: ./actions/ci + with: + workspace_name: YOUR_PACKAGE_NAME + workspace_path: PATH_TO_YOUR_PACKAGE +``` +> NOTE: you should test your configuration on [your local machine](../.github/CI_CONTRIBUTING.md) if +> possible. \ No newline at end of file diff --git a/packages/sdk/shopify-oxygen/tsconfig.ref.json b/packages/sdk/shopify-oxygen/tsconfig.ref.json index d5b9e9c75f..9084a67bfc 100644 --- a/packages/sdk/shopify-oxygen/tsconfig.ref.json +++ b/packages/sdk/shopify-oxygen/tsconfig.ref.json @@ -1,10 +1,7 @@ { - "extends": "../../../tsconfig.json", + "extends": "./tsconfig.json", "compilerOptions": { "composite": true, - "rootDir": ".", - "outDir": "dist" }, - "include": ["src/**/*.ts"], - "exclude": ["**/*.test.ts", "dist", "node_modules", "__tests__", "example"] + "include": ["src/**/*", "package.json"], } diff --git a/packages/sdk/shopify-oxygen/typedoc.json b/packages/sdk/shopify-oxygen/typedoc.json new file mode 100644 index 0000000000..7ac616b544 --- /dev/null +++ b/packages/sdk/shopify-oxygen/typedoc.json @@ -0,0 +1,5 @@ +{ + "extends": ["../../../typedoc.base.json"], + "entryPoints": ["src/index.ts"], + "out": "docs" +} diff --git a/release-please-config.json b/release-please-config.json index f8325b4429..0f0dbc1d68 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -12,6 +12,14 @@ "bump-minor-pre-major": true, "prerelease": true }, + "packages/sdk/shopify-oxygen": { + "bump-minor-pre-major": true, + "prerelease": true, + "release-as": "0.1.0", + "extra-files": [ + "src/platform/OxygenInfo.ts" + ] + }, "packages/shared/common": {}, "packages/shared/sdk-client": {}, "packages/shared/sdk-server": {}, diff --git a/tsconfig.json b/tsconfig.json index edc4dd75e0..1b4cea3bb6 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -87,6 +87,9 @@ }, { "path": "./packages/ai-providers/server-ai-vercel/tsconfig.ref.json" + }, + { + "path": "./packages/sdk/shopify-oxygen/tsconfig.ref.json" } ] } From 9a544ccbeab67f819d8c14ea7e49cf81377f6b9f Mon Sep 17 00:00:00 2001 From: Steven Zhang Date: Thu, 13 Nov 2025 10:13:58 -0600 Subject: [PATCH 2/2] doc: combined publishing doc per PR comment This commit also made some small changes to the release please config --- CONTRIBUTING.md | 3 + contributing/initial-package-publish.md | 20 ----- .../publishing-pre-release-modules.md | 71 --------------- contributing/publishing.md | 90 +++++++++++++++++++ release-please-config.json | 2 +- 5 files changed, 94 insertions(+), 92 deletions(-) delete mode 100644 contributing/initial-package-publish.md delete mode 100644 contributing/publishing-pre-release-modules.md create mode 100644 contributing/publishing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e539cf549..f836da112a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,6 +69,9 @@ describe('given a mock filesystem and memory feature store', { /* tests */}) These then combined to create an understandable test name: `given a mock filesystem and memory feature store > it does not load flags prior to start` +--- +For docs on our module publishing process, see [our publishing doc](contributing/publishing.md) + ## Development Guidelines These are a series of recommendations for developing code in this repository. Not all existing code will comply diff --git a/contributing/initial-package-publish.md b/contributing/initial-package-publish.md deleted file mode 100644 index 031bce2170..0000000000 --- a/contributing/initial-package-publish.md +++ /dev/null @@ -1,20 +0,0 @@ -# Initial Package Publishing - -When publishing a package for the first time, you must complete several steps not part of a typical package release. - -1. If you are not releasing a 1.0, then you need to set the `release-as` setting in the `release-please-config.json` to your desired version. - Release-please will include all conventional commits, but for the initial release, you do not want them, so you should set the `bootstrap-sha` to the current SHA. - -``` - "packages/type/my-package": { - "bump-minor-pre-major": true // Set this if you are releasing a pre 1.0. - "release-as": "0.1.0", // Set this for a pre 1.0 release. - "bootstrap-sha": "MY_SHA" // Set this to the most recent SHA. - } -``` - -2. After the release PR is created you will need to manual update the PR it creates to format the changelog as desired. Ensuring the notice is at the top, and adding any language required for the initial release. - -3. When you are ready to release, merge the PR. If there are other packages being released, then check to ensure that package is ready to be released. - -4. Remove "release-as" and "boostrap-sha" from the `release-please-config.json`. diff --git a/contributing/publishing-pre-release-modules.md b/contributing/publishing-pre-release-modules.md deleted file mode 100644 index eeae8585bb..0000000000 --- a/contributing/publishing-pre-release-modules.md +++ /dev/null @@ -1,71 +0,0 @@ -# Creating pre-releases modules - -The following steps are to create a pre release modules which would walk through the initial -CI work needed for new SDKs. - -## 1. Extend `release-please-config.json` - -Add a record of your new SDK package to `packages` -``` -"PATH_TO_YOUR_PACKAGE": { - "prerelease": true, - "bump-minor-pre-major": true, - "release-as": "0.1.0" -} -``` -> NOTE: the `PATH_TO_YOUR_PACKAGE` needs to match the path in `package.json` -> eg `packages/sdk/server-node` - -This is the minimum changes you need to do. `bump-minor-pre-major` option means only -minor version will be incremented while your package is in pre-release state. -> Pre-release packages **MUST** be in major version `0` - -## 2. Add initial release manifest - -Add the following to `.release-please-manifest.json` -``` -"PATH_TO_YOUR_PACKAGE": "0.0.0" -``` - -## 3. Add option to manual workflows - -Add `PATH_TO_YOUR_PACKAGE` to the `on.workflow_dispatch.inputs.workspace_path.options` -array in the following files: -- [`manual-publish-docs.yml`](./workflows/manual-publish-docs.yml) -- [`manual-publish.yml`](./workflows/manual-publish.yml) - -## 4. Create a CI non-release workflow for just the project - -You will add a file in the `.github/workflows` directory that tells GHA (mostly) how to -test your SDK. Below is a simple template to get started: -``` -name: sdk/YOUR_SDK - -on: - push: - branches: [main, 'feat/**'] - paths-ignore: - - '**.md' - pull_request: - branches: [main, 'feat/**'] - paths-ignore: - - '**.md' - -jobs: - build-test-YOUR_SDK: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: lts/* - registry-url: 'https://registry.npmjs.org' - - id: shared - name: Shared CI Steps - uses: ./actions/ci - with: - workspace_name: YOUR_PACKAGE_NAME - workspace_path: PATH_TO_YOUR_PACKAGE -``` -> NOTE: you should test your configuration on [your local machine](../.github/CI_CONTRIBUTING.md) if -> possible. \ No newline at end of file diff --git a/contributing/publishing.md b/contributing/publishing.md new file mode 100644 index 0000000000..668c45c42d --- /dev/null +++ b/contributing/publishing.md @@ -0,0 +1,90 @@ +# Publishing SDKs + +Publishing a new SDK package in this monorepo typically happens in 2 +phases: initial package publishing phase and stable release phase. + +> [!NOTE] +> If you are moving an existing package to this monorepo, you should +> still read through the [initial publishing](#initial-package-publishing) +> and follow the relevant steps to initialize the CI implementation. + +## Initial Package Publishing + +When publishing a package for the first time, developers must complete several steps not part of a typical package release. This phase is +designed to: + 1. Establish the CI implementation for the new package + 2. Generate pre-release builds for testing + +### Step 1. Extend `release-please-config.json` + +When doing the initial release, you will need to add a new record to +[`release-please-config.json`](../release-please-config.json): +``` +"packages/type/my-package": { + "bump-minor-pre-major": true, + "release-as": "0.1.0", + "bootstrap-sha": "MY_SHA" +} +``` +> [!TIP] +> `bump-minor-pre-major` only needs to be set if you are publishing +> unstable releases (major version `0`). This option ensures that +> breaking changes will only increment minor version. + +> [!TIP] +> `bootstrap-sha` will ensure that the conventional commits are +> calculated from a certain point and not the whole package history. +> You can find the appropriate commit sha using `git log`. + +## 2. Add initial release manifest + +Add the following to `.release-please-manifest.json` +``` +"packages/type/my-package": "0.0.0" +``` + +## 3. Add option to manual workflows + +Add `PATH_TO_YOUR_PACKAGE` to the `on.workflow_dispatch.inputs.workspace_path.options` +array in the following files: +- [`manual-publish-docs.yml`](../.github/workflows/manual-publish-docs.yml) +- [`manual-publish.yml`](../.github/workflows/manual-publish.yml) + +## 4. Create a CI non-release workflow for just the project + +You will add a file in the `.github/workflows` directory that tells GHA (mostly) how to +test your SDK. Below is a simple template to get started: +``` +name: sdk/YOUR_SDK + +on: + push: + branches: [main, 'feat/**'] + paths-ignore: + - '**.md' + pull_request: + branches: [main, 'feat/**'] + paths-ignore: + - '**.md' + +jobs: + build-test-YOUR_SDK: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: lts/* + registry-url: 'https://registry.npmjs.org' + - id: shared + name: Shared CI Steps + uses: ./actions/ci + with: + workspace_name: YOUR_PACKAGE_NAME + workspace_path: PATH_TO_YOUR_PACKAGE +``` +> ![TIP] +> you should test your configuration on [your local machine](../.github/CI_CONTRIBUTING.md) if +> possible. + + \ No newline at end of file diff --git a/release-please-config.json b/release-please-config.json index 0f0dbc1d68..c748ecd195 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -14,8 +14,8 @@ }, "packages/sdk/shopify-oxygen": { "bump-minor-pre-major": true, - "prerelease": true, "release-as": "0.1.0", + "bootstrap-sha": "e70e4846d03f7ca2b6ef267efa90a24810e9364a", "extra-files": [ "src/platform/OxygenInfo.ts" ]