Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

Add documentation for adding new crates (#12300)

Alex Crichtonec76a6b2a6f1
diff --git a/docs/contributing-coding-guidelines.md b/docs/contributing-coding-guidelines.md
index 9286cc19da..30a08c3c9f 100644
--- a/docs/contributing-coding-guidelines.md
+++ b/docs/contributing-coding-guidelines.md
@@ -262,6 +262,41 @@ crates to the repository and where to place/name them:
workspace-local usage, meaning that the "internal" part is only relevant on
crates.io.
+### Adding Crates
+
+Adding a new crate to the Wasmtime workspace takes a bit of care. Wasmtime uses
+crates.io trusted publishing meaning that all crates are published from CI in a
+specific workflow. This means that crates must exist on crates.io prior to their
+first publication from the Wasmtime workspace and be configured for trusted
+publishing.
+
+The process for adding a new crate to the workspace looks like:
+
+1. In a PR a new crate is added and this documentation probably isn't read to
+ start out with.
+2. CI will fail in the "verify-publish" job because this crate doesn't exist on
+ crates.io.
+3. The PR author should publish a placeholder crate to crates.io.
+4. The PR author should go to "Settings" on crates.io, click on "Add" under
+ "Trusted Publishing", and enter the following:
+ fields:
+ * Publisher: `GitHub`
+ * Repository Owner: `bytecodealliance`
+ * Repository name: `wasmtime`
+ * Workflow filename: `publish-to-cratesio.yml`
+ * Environment name: `publish`
+5. The PR author should then check the box for requiring all publishes to use
+ the trusted publishing workflow.
+6. The PR author should invite the `wasmtime-publish` user to this crate.
+7. A Wasmtime maintainer, with access to the BA 1password vault, will log in to
+ crates.io as the `wasmtime-publish` user to accept the invite. Wasmtime
+ maintainers should double-check all of the settings and remove the original
+ owner of the crate so just `wasmtime-publish` owns the crate.
+
+This ensures that when publication time rolls around the crate is already
+reserved on GitHub and the publication workflow will succeed. After the initial
+publication the crate is managed by Wasmtime maintainers.
+
### Use of `unsafe`
Wasmtime is a project that contains `unsafe` Rust code. Wasmtime is also used in
diff --git a/scripts/publish.rs b/scripts/publish.rs
index 0e1ee1c83d..1987e519b7 100644
--- a/scripts/publish.rs
+++ b/scripts/publish.rs
@@ -587,9 +587,11 @@ fn verify(crates: &[Crate]) {
"
failed to get owners for {name}
-If this crate does not exist on crates.io yet please ping wasmtime maintainers
-to add the crate on crates.io as a small shim. When doing so please remind them
-that the trusted publishing workflow must be configured as well.
+If this crate does not exist on crates.io yet please visit
+
+ https://docs.wasmtime.dev/contributing-coding-guidelines.html#adding-crates
+
+and follow the instructions there
",
name = name,
);
@@ -599,9 +601,11 @@ that the trusted publishing workflow must be configured as well.
if !owners.contains("\"id\":73222,") {
panic!(
"
-crate {name} is not owned by wasmtime-publish, please run:
+crate {name} is not owned by wasmtime-publish, please visit:
- cargo owner -a wasmtime-publish {name}
+ https://docs.wasmtime.dev/contributing-coding-guidelines.html#adding-crates
+
+and follow the instructions there
",
name = name,
);
@@ -612,10 +616,11 @@ crate {name} is not owned by wasmtime-publish, please run:
if false && owners.split("\"id\"").count() != 2 {
panic!(
"
-crate {name} is not exclusively owned by wasmtime-publish
+crate {name} is not exclusively owned by wasmtime-publish, please visit:
+
+ https://docs.wasmtime.dev/contributing-coding-guidelines.html#adding-crates
-Please contact wasmtime maintainers to ensure that `wasmtime-publish` is the
-only listed owner of the crate.
+and follow the instructions there
",
name = name,
);