From 414fd8bc04f01b9ef670c49952dea6e55eafaebc Mon Sep 17 00:00:00 2001
From: Christoph Knittel <ck@cca.io>
Date: Mon, 21 Sep 2026 19:47:20 +0200
Subject: [PATCH] Document npm package bootstrap process

Signed-off-by: Christoph Knittel <ck@cca.io>
---
 CONTRIBUTING.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8f33ed0cd2..e47ecb4414 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -184,6 +184,59 @@ To make sure that no files are added to or removed from the `rescript`, `@rescri
 
 After adding a new file to the repository that should go into one of the npm packages - e.g., a new stdlib module -, run `make artifacts`.
 
+## Adding a New npm Package
+
+npm trusted publishing can only be configured after a package exists in the
+registry. Before the package's first real release, create it with a minimal
+`0.0.0` version under a temporary `bootstrap` tag. This keeps `latest` and the
+normal release tags unchanged. The npm account used for these commands needs
+write access to the package scope and two-factor authentication enabled. Run
+`npm login` first if the account is not already authenticated locally.
+
+Run the following outside the repository, replacing `@rescript/example` with
+the new package name:
+
+```sh
+bootstrap_dir="$(mktemp -d)"
+cd "$bootstrap_dir"
+
+npm init --yes
+npm pkg set \
+  name="@rescript/example" \
+  version="0.0.0" \
+  license="MIT" \
+  repository.type="git" \
+  repository.url="git+https://github.com/rescript-lang/rescript.git"
+
+npm publish \
+  --access public \
+  --tag bootstrap \
+  --provenance=false
+```
+
+Then use npm 11.15 or newer to authorize this repository's protected publish
+job as the package's trusted publisher:
+
+```sh
+npm trust github @rescript/example \
+  --file publish.yml \
+  --repository rescript-lang/rescript \
+  --environment npm-release \
+  --allow-publish \
+  --yes
+```
+
+The normal `Publish` workflow can now publish the package with provenance. Once
+the first real version has been published successfully, remove the temporary
+tag:
+
+```sh
+npm dist-tag rm @rescript/example bootstrap
+```
+
+The `0.0.0` version remains in npm's immutable package history but is not
+selected by `latest` or any of the repository's release tags.
+
 ## Test the compiler
 
 ### Single file