Skip to content

publishing.md

Latest commit

 

History

History
140 lines (104 loc) · 4.55 KB

publishing.md

File metadata and controls

140 lines (104 loc) · 4.55 KB
Raw

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 and follow the relevant steps to initialize the CI implementation.

Publishing Workflows

This repository uses the release-please.yml workflow for all publishing operations:

  • Automated Publishing: When changes are pushed to main, release-please automatically creates release PRs based on conventional commits. When these PRs are merged, packages are automatically published to npm.

  • Manual Publishing: The workflow can be triggered manually via the GitHub Actions UI to publish a specific package. This is useful for:

    • Pre-release versions
    • Hotfixes or backports
    • Correcting publishing errors
    • Publishing to JSR (JavaScript Registry)

    Manual triggers support prerelease flags and dry-run mode.

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 0. Create a placeholder npm package

This repo uses OIDC authentication to establish trust between npmjs and github. As such we need to first create the npm package on npmjs in order to establish the trust. See this discussion

Run the placeholder publish script:

./scripts/publish-placeholder-package.sh packages/type/my-package

The script handles npm login/npm logout internally and publishes an empty 0.0.0 package under the snapshot tag so it does not become latest.

After completing this step, follow this doc to configure trusted publishing on the new NPM package, then mark the package public.

For this repo, you should use the following values:
Publisher Github Actions
Organization launchdarkly
Repository js-core
Workflow filename release-please.yml

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:

"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:

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 if possible.