2 files changed
+39
.agents/skills/ci-cd/SKILL.md
+6
@@ -690,6 +690,12 @@ One practical warning: the Ruby gem release depends on crates.io propagation. If
690
691
## Common mistakes
692
693
+**SDK npm version out of sync with Rust crate version**
694
+`sdk/npm/smbcloud-auth/package.json` must have the same version as `crates/smbcloud-auth-sdk-wasm/Cargo.toml`. The `prepare-package.mjs` script compares them at build time and throws a hard error on mismatch. When bumping workspace crate versions for a release, always update the npm package version in the same commit. Forgetting this causes the `check-npm-sdk` CI job and the `release-sdk-npm` workflow to fail.
695
+
696
+**Tagging a release on a feature branch instead of `development`**
697
+Always tag on `development` (the mainline branch). Tagging on a feature branch leaves `development` without the release commit, making git history confusing and future releases error-prone. Merge the feature branch into `development` first, then tag. If a tag was already placed on the wrong commit, move it with `git tag -f v<version>` and `git push origin v<version> --force`.
698
+
699
**Building the full workspace in release workflows**
700
Always pass `--package smbcloud-cli` to `cargo build` and `cargo publish`. Omitting it builds `smbcloud-auth-sdk-py` (PyO3 cdylib) which fails on platforms without a matching Python interpreter.
701
.agents/skills/smbcloud-cli-release/SKILL.md
+33
@@ -19,6 +19,9 @@ Use this skill when work touches any part of the smbCloud CLI distribution flow:
19
Use these files as the release source of truth:
20
21
- Rust crate version and binary name: `crates/cli/Cargo.toml`
22
+- SDK WASM crate version: `crates/smbcloud-auth-sdk-wasm/Cargo.toml`
23
+- SDK npm package version: `sdk/npm/smbcloud-auth/package.json`
24
+- SDK npm build script: `sdk/npm/smbcloud-auth/prepare-package.mjs`
25
- npm release workflow: `.github/workflows/release-npm.yml`
26
- PyPI release workflow: `.github/workflows/release-pypi.yml`
27
- npm platform package generator: `npm/scripts/render-platform-package.cjs`
@@ -27,6 +30,36 @@ Use these files as the release source of truth:
30
- PyPI package metadata: `pypi/pyproject.toml`
31
- PyPI package README: `pypi/README.md`
32
33
+## Version sync rules
34
+
35
+The SDK npm package `@smbcloud/sdk-auth` must have its version in `sdk/npm/smbcloud-auth/package.json` match the version in `crates/smbcloud-auth-sdk-wasm/Cargo.toml` exactly. The `prepare-package.mjs` script enforces this at build time and will fail CI if they diverge.
36
+
37
+When bumping workspace crate versions for a release, always update `sdk/npm/smbcloud-auth/package.json` in the same commit.
38
+
39
+## Tagging discipline
40
+
41
+Always tag releases on the `development` branch (the mainline). Never tag on a feature branch.
42
+
43
+Reasoning:
44
+
45
+- The release commit history stays clean and linear on the default branch.
46
+- `cargo workspaces publish --allow-branch "*"` accepts any branch, but downstream workflows dispatch from the tag ref, so the tagged commit must contain all intended changes.
47
+- Tagging on a feature branch leaves `development` without the release commit and makes git history confusing.
48
+
49
+Workflow:
50
+
51
+1. Merge the feature branch into `development` with `--no-ff`.
52
+2. Tag on `development`: `git tag v<version>`.
53
+3. Push both: `git push origin development && git push origin v<version>`.
54
+
55
+If a tag was placed on the wrong commit (e.g. before a last-minute fix), move it:
56
+
57
+1. Merge the fix into `development`.
58
+2. Force-move the tag: `git tag -f v<version>`.
59
+3. Force-push the tag: `git push origin v<version> --force`.
60
+
61
+The `release-crate.yml` orchestrator triggers on `push.tags: "v*.*.*"`, so the force-push will re-trigger the full release chain.
62
+
63
## Release model
64
65
There are two public distribution channels.