1  # Release Process
  2  
  3  ## Versioning
  4  
  5  Auths follows Semantic Versioning (SemVer). The project is currently pre-1.0 (`0.x.y`).
  6  
  7  | Increment | Meaning |
  8  |-----------|---------|
  9  | `0.y.z` to `0.y.(z+1)` | Bug fixes, minor additions |
 10  | `0.y.z` to `0.(y+1).0` | Breaking changes, significant features |
 11  
 12  All pre-1.0 versions are unstable. The public API may change at any time.
 13  
 14  The current workspace version is defined in the root `Cargo.toml`:
 15  
 16  ```toml
 17  [workspace.package]
 18  version = "0.0.1-rc.5"
 19  ```
 20  
 21  ## Release steps
 22  
 23  ### Using the justfile (recommended)
 24  
 25  The `justfile` at the repo root automates all release steps:
 26  
 27  ```bash
 28  just release 0.x.y
 29  ```
 30  
 31  This handles pre-flight checks (clean working tree, branch, remote sync), creates and pushes the annotated tag, and opens the GitHub Actions run in your browser. GitHub Actions then builds binaries, creates the release, and triggers the Homebrew formula update.
 32  
 33  ### One-time CI signing setup
 34  
 35  Before the first release, GitHub Actions needs a device key and identity bundle for artifact signing:
 36  
 37  ```bash
 38  just ci-setup
 39  ```
 40  
 41  This creates a limited-capability CI device key, exports it as an encrypted keychain, and sets three GitHub secrets: `AUTHS_CI_PASSPHRASE`, `AUTHS_CI_KEYCHAIN`, and `AUTHS_CI_IDENTITY_BUNDLE`. Artifact signing is skipped gracefully if these secrets are missing.
 42  
 43  Re-run `ci-setup` only if the CI device key is revoked or the identity repo changes significantly.
 44  
 45  ### Manual steps (if needed)
 46  
 47  #### 1. Ensure main is stable
 48  
 49  ```bash
 50  cargo build
 51  cargo nextest run --workspace
 52  cargo test --all --doc
 53  cargo fmt --check --all
 54  cargo clippy --all-targets --all-features -- -D warnings
 55  ```
 56  
 57  #### 2. Update version numbers
 58  
 59  ```bash
 60  # If using cargo-edit:
 61  cargo set-version 0.x.y
 62  cargo check  # updates Cargo.lock
 63  
 64  git add .
 65  git commit -m "Bump version to v0.x.y"
 66  git push origin main
 67  ```
 68  
 69  #### 3. Create Git tag
 70  
 71  ```bash
 72  git tag -a v0.x.y -m "Release v0.x.y"
 73  git push origin v0.x.y
 74  ```
 75  
 76  GitHub Actions picks up the `v*` tag and runs `.github/workflows/release.yml`.
 77  
 78  #### 4. Publish Rust crates
 79  
 80  ```bash
 81  cargo publish -p auths
 82  cargo publish -p auths-crypto
 83  cargo publish -p auths-index
 84  cargo publish -p auths-policy
 85  cargo publish -p auths-telemetry
 86  sleep 60
 87  cargo publish -p auths-verifier
 88  cargo publish -p auths-keri
 89  cargo publish -p auths-core
 90  sleep 60
 91  cargo publish -p auths-infra-http
 92  sleep 60
 93  cargo publish -p auths-id
 94  sleep 60
 95  cargo publish -p auths-storage
 96  cargo publish -p auths-sdk
 97  sleep 60
 98  cargo publish -p auths-infra-git
 99  sleep 60
100  cargo publish -p auths-cli
101  ```
102  
103  #### 5. Publish SDK packages (optional)
104  
105  ```bash
106  # Python
107  cd packages/auths-verifier-python
108  maturin build --release
109  twine upload target/wheels/*
110  
111  # JavaScript
112  cd packages/auths-verifier-ts
113  npm run build
114  npm publish
115  
116  # Go
117  # Tag the module: git tag packages/auths-verifier-go/v0.x.y
118  ```
119  
120  ## SDK versioning
121  
122  SDK packages (Python, TypeScript, Go, Swift) have independent version numbers from the Rust crates.
123  
124  | Component | Registry |
125  |-----------|----------|
126  | Rust crates (`auths-core`, `auths-verifier`, ...) | crates.io |
127  | Python SDK (`auths-verifier`) | PyPI |
128  | TypeScript SDK (`@auths/verifier`) | npm |
129  
130  SDK versions track their own binding API stability. A breaking change in the Python wrapper bumps the Python version even if the underlying Rust API did not change. An internal Rust refactor that does not affect the binding surface does not require an SDK version bump.
131  
132  ### Automated SDK publishing
133  
134  SDK publishing is automated via GitHub Actions triggered by `v*` tags:
135  
136  - **Python**: `.github/workflows/publish-python.yml` -- builds platform wheels with maturin and publishes to PyPI using Trusted Publisher.
137  - **TypeScript**: `.github/workflows/publish-typescript.yml` -- builds WASM + TypeScript and publishes to npm.
138  
139  ## CI matrix
140  
141  | Platform | Architecture |
142  |----------|-------------|
143  | Ubuntu | x86_64 |
144  | macOS | aarch64 |
145  | Windows | x86_64 |
146  
147  Rust version: 1.93+ (check `rust-toolchain.toml`).
148  
149  ## What CI does on a release tag
150  
151  When a `v*` tag is pushed:
152  
153  1. Runs the full test suite across all three platforms.
154  2. Builds release binaries for each platform.
155  3. Creates a GitHub Release with the binaries attached.
156  4. Signs artifacts with the CI device key (if secrets are configured).
157  5. Triggers the Homebrew formula update.
158  6. Triggers SDK publishing workflows (Python, TypeScript).