diff --git a/.changeset/create-oidc-docs.md b/.changeset/create-oidc-docs.md new file mode 100644 index 0000000000..7bfb6388bc --- /dev/null +++ b/.changeset/create-oidc-docs.md @@ -0,0 +1,5 @@ +--- +'@lg-tools/create': patch +--- + +Add CLI output and documentation for npm trusted publishing (OIDC) initial publish requirement diff --git a/DEVELOPER.md b/DEVELOPER.md index f2e02e80d4..b49583188d 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -197,6 +197,44 @@ If you want to stop publishing to and/or reading from your local Verdaccio serve - If you are using any `leafygreen-ui` dependencies in your new component, add the dependency to the component directory's `tsconfig.json`. - Run `pnpm run init` to link all packages before starting development +## Publishing a new package + +This repository uses [npm trusted publishing with OIDC](https://docs.npmjs.com/trusted-publishers) for secure automated releases. However, new packages require a manual first publish before automation can take over. + +### Initial Publish (Required for New Packages) + +When you create a new package, you must manually publish the first version: + +1. **Build the package** + + ```bash + pnpm build --filter="" + ``` + +2. **Publish to npm** + + ```bash + cd / + npm publish --access public + ``` + +3. **Configure trusted publisher** on [npmjs.com](https://www.npmjs.com): + - Navigate to your package → Settings → Trusted Publishers + - Add a trusted publisher: + - **Repository**: `mongodb/leafygreen-ui` + - **Workflow**: `release.yml` + +### Subsequent Releases + +After the initial publish and trusted publisher configuration, all future releases are handled automatically: + +1. Add a changeset: `pnpm changeset` +2. Merge your PR to `main` +3. The "Version Packages" PR will be created automatically +4. Merge the "Version Packages" PR to publish to npm + +For more details on changesets and versioning, see the [README](./README.md#committing). + ## Marking a Storybook story to be imported in mongodb.design The mongodb.design website will automatically import the `*.story.tsx` file from its installed package directory to render its live example. By default, the first exported story from the `*.story.tsx` file will be rendered. To specify a different story to be rendered, define the following in the Storybook file's Meta object: diff --git a/README.md b/README.md index 23995b85f3..6cda8884b3 100644 --- a/README.md +++ b/README.md @@ -254,7 +254,9 @@ Note: it's important to follow the kebab-casing convention described above. ### Initial Release -The starting version in the generated `package.json` will be 0.0.1, but this will not be published to npm automatically. A new package is only published after its first changeset is added and the resulting "Version Packages" pull request is merged into the `main` branch. +The starting version in the generated `package.json` will be 0.0.1, but this will not be published to npm automatically. +**Note: You must manually publish the first version** of your new package before the automated release workflow can take over. +See [DEVELOPER.md](./DEVELOPER.md#publishing-a-new-package) for detailed instructions. Note: The `create-package` script automatically generates a starter changeset file. By default this is marked as a **minor** release, which will lead to an initial release of 0.1.0. If you'd like the initial release to be a **major** version (1.0.0), this starter changeset file must be manually edited. diff --git a/tools/create/README.md b/tools/create/README.md index ee1ec1559e..aa54b6fc1f 100644 --- a/tools/create/README.md +++ b/tools/create/README.md @@ -10,6 +10,11 @@ Use from `@lg-tools/cli`: lg create ``` +## Initial Publish Required + +After creating a new package, **you must manually publish the first version** before the automated release workflow can take over. +See [DEVELOPER.md](../../DEVELOPER.md#publishing-a-new-package) for detailed instructions. + ## Options ### Scope diff --git a/tools/create/src/index.ts b/tools/create/src/index.ts index 4802866b1a..22b398b9f0 100644 --- a/tools/create/src/index.ts +++ b/tools/create/src/index.ts @@ -3,6 +3,7 @@ import chalk from 'chalk'; import { getComponentRootDirectory } from './utils/getComponentRootDirectory'; import { getScope } from './utils/getScope'; +import { printInitialPublishInstructions } from './utils/printInitialPublishInstructions'; import { CreatePackageOptions } from './create.types'; import { createChangeset } from './createChangeset'; import { createComponent } from './createComponent'; @@ -41,5 +42,8 @@ export function createPackage(name: string, options: CreatePackageOptions) { name, scope, }); + + // Print instructions for initial publish + printInitialPublishInstructions(); } } diff --git a/tools/create/src/utils/printInitialPublishInstructions.ts b/tools/create/src/utils/printInitialPublishInstructions.ts new file mode 100644 index 0000000000..773157a510 --- /dev/null +++ b/tools/create/src/utils/printInitialPublishInstructions.ts @@ -0,0 +1,10 @@ +/* eslint-disable no-console */ +import chalk from 'chalk'; + +export function printInitialPublishInstructions() { + console.log(` +${chalk.yellow.bold('⚠️ Manual first publish required')} +You must manually publish the first version before automated releases can take over. +See ${chalk.cyan('README.md#initial-release')} for instructions. +`); +}