From 477dbab9ac306ce60f90299ae2b6ff9ee943e320 Mon Sep 17 00:00:00 2001 From: Lazyartist1 <183598248+Lazyartist1@users.noreply.github.com> Date: Sun, 30 Aug 2026 16:31:52 +0100 Subject: [PATCH 1/2] docs: add CHANGELOG.md and document release process (#227) --- CHANGELOG.md | 61 +++++++++++++++++++++++++++ README.md | 5 +++ docs/RELEASING.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 171 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 docs/RELEASING.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2c5acb3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,61 @@ +# Changelog + +All notable changes to Signet will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +For release instructions and versioning procedures, see [`docs/RELEASING.md`](docs/RELEASING.md). + +--- + +## Deployed Contract Registry + +| Network | Contract | Contract ID | Deployed Date | Verification | +| --- | --- | --- | --- | --- | +| **Stellar Testnet** | `identity-registry` | `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC` | 2026-07-09 | Active (Soroban RPC) | +| **Stellar Mainnet** | `identity-registry` | *Pending deployment* | *TBD* | — | + +--- + +## [Unreleased] + +### Added +- Area-based code review assignments via `.github/CODEOWNERS` ([#231](https://github.com/blockchain-maxis/signet/issues/231)). +- CI concurrency group to cancel superseded in-progress workflow runs on push ([#229](https://github.com/blockchain-maxis/signet/issues/229)). +- Release procedure documentation and versioning policy in `docs/RELEASING.md` ([#227](https://github.com/blockchain-maxis/signet/issues/227)). +- Identity Registry migration runbook in `docs/CONTRACT_MIGRATION.md` ([#308](https://github.com/blockchain-maxis/signet/pull/308)). +- Multi-device and per-address session revocation with Upstash Redis backend support ([#307](https://github.com/blockchain-maxis/signet/pull/307)). +- Contract error drift checker `scripts/check-contract-errors.mjs` guarding Rust contract error codes against UI translation sync ([#238](https://github.com/blockchain-maxis/signet/pull/238)). +- Live testnet E2E seam test for claim → resolve → profile flow ([#240](https://github.com/blockchain-maxis/signet/pull/240)). + +### Changed +- Public SDK type surface stabilized ahead of `@signet/sdk@0.1.0` release ([#310](https://github.com/blockchain-maxis/signet/pull/310)). +- Health route `/api/health` now reports nonce and rate-limit store status dynamically ([#309](https://github.com/blockchain-maxis/signet/pull/309)). +- Connect wallet badge dynamically renders the active configured network from `NEXT_PUBLIC_STELLAR_NETWORK` ([#168](https://github.com/blockchain-maxis/signet/issues/168)). + +### Fixed +- Added static `/handles` route to sitemap indexing ([#222](https://github.com/blockchain-maxis/signet/issues/222)). +- Smoke tests now rely on semantic heading selectors instead of brittle copy assertions ([#219](https://github.com/blockchain-maxis/signet/issues/219)). +- Extended contract instance TTL on read paths to prevent storage archival of active registries ([#242](https://github.com/blockchain-maxis/signet/pull/242)). + +--- + +## [0.1.0] - 2026-08-28 + +### Added +- Initial release of Signet developer career record platform. +- **Identity Registry Contract** (`packages/contracts/identity-registry`): + - On-chain handle claim, transfer, and release methods with owner authorization (`require_auth`). + - Read-path TTL extension for bound records and contract instance. + - Comprehensive unit test suite and property-based invariant testing. +- **Web Application** (`apps/web`): + - Landing page, how-it-works guide, and public `/p/{handle}` profiles. + - Discovery directory at `/handles` reading direct Soroban events. + - Stellar Wallets Kit wallet connection and SEP-10 Sign-In With Stellar (SIWS) authentication. + - tRPC API endpoints for profile queries, handle resolution, and health reporting. +- **Indexer Worker** (`apps/indexer`): + - Horizon polling worker for deployment and operation indexing into PostgreSQL. + - Attestation event parser for on-chain identity binding events. +- **TypeScript SDK** (`@signet/sdk`): + - Read-only client for querying profiles, resolved handles, and platform health. diff --git a/README.md b/README.md index 7cd9765..8297b9d 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,11 @@ set from the event stream. Both are CI gates ([`ci.yml`](.github/workflows/ci.yml)), alongside `lint`, `typecheck`, `build` and the wasm contract build. +## Releases and changelog + +- **[`CHANGELOG.md`](CHANGELOG.md)** — Record of notable changes, version history, and deployed contract addresses. +- **[`docs/RELEASING.md`](docs/RELEASING.md)** — Release procedure, Semantic Versioning policy, and tagging conventions. + ## License Signet is licensed under the Apache License 2.0 — see [`LICENSE`](LICENSE) for the diff --git a/docs/RELEASING.md b/docs/RELEASING.md new file mode 100644 index 0000000..6af1575 --- /dev/null +++ b/docs/RELEASING.md @@ -0,0 +1,105 @@ +# Release Process & Versioning Policy + +This document defines the release procedure, versioning semantics, and tagging conventions for the Signet repository (`blockchain-maxis/signet`). + +--- + +## 1. Versioning Policy + +Signet follows [Semantic Versioning (SemVer 2.0.0)](https://semver.org/spec/v2.0.0.html) across all packages and on-chain contracts: `MAJOR.MINOR.PATCH`. + +```text +MAJOR (X.0.0) -> Breaking API changes, breaking contract storage layouts, or breaking schema migrations +MINOR (0.X.0) -> Backwards-compatible features, new API endpoints, non-breaking contract methods +PATCH (0.0.X) -> Backwards-compatible bug fixes, security patches, internal refactors +``` + +### Monorepo Scope Breakdown + +| Component | Scope | Version Reference | Version Impact | +| --- | --- | --- | --- | +| **`@signet/sdk`** | External TypeScript SDK | `packages/sdk/package.json` | Published to npm registry; breaking changes bump `MAJOR` | +| **`identity-registry`** | Soroban Rust contract | `packages/contracts/identity-registry/Cargo.toml` | On-chain bytecode deployed to permanent addresses; requires migration runbook if storage format changes | +| **`@signet/web`** | Next.js frontend & tRPC API | `apps/web/package.json` | Web application deployment; tracks overall platform release | +| **`@signet/indexer`** | Ingestion worker | `apps/indexer/package.json` | Background worker syncing events to Postgres | +| **`@signet/types`** | Shared type definitions | `packages/types/package.json` | Internal workspace dependency | + +--- + +## 2. Tagging Conventions + +All releases are tracked via Git tags pushed to `main`: + +- **Platform Releases**: `vX.Y.Z` (e.g. `v0.1.0`) — Tracks coordinated platform deployments. +- **SDK Package Releases**: `sdk-vX.Y.Z` (e.g. `sdk-v0.1.0`) — Tracks npm releases of `@signet/sdk`. +- **Contract Releases**: `contract-vX.Y.Z` (e.g. `contract-v0.1.0`) — Tracks verified contract build hashes and on-chain deployment references. + +--- + +## 3. Release Checklist & Step-by-Step Procedure + +### Phase 1: Pre-Release Verification + +Before tagging or releasing any component, verify that all CI gates and local suites pass cleanly: + +```bash +# 1. Monorepo lint, typecheck, tests, and build +pnpm lint +pnpm typecheck +pnpm test +pnpm build + +# 2. Documentation and error consistency checks +node scripts/check-docs.mjs +node scripts/check-contract-errors.mjs + +# 3. Contract unit tests and wasm size budget +cd packages/contracts +cargo test +cargo build --target wasm32v1-none --release +cd ../.. +``` + +### Phase 2: Update Version Numbers & Changelog + +1. Update version numbers in the target `package.json` or `Cargo.toml`. +2. Move unreleased changes in [`CHANGELOG.md`](../CHANGELOG.md) under a new dated release header `## [X.Y.Z] - YYYY-MM-DD`. +3. If a contract was deployed, record the contract ID and network in the Deployed Contract Registry table in [`CHANGELOG.md`](../CHANGELOG.md). +4. Commit the changes: + ```bash + git commit -m "chore(release): prepare vX.Y.Z release" + ``` + +### Phase 3: Tagging & GitHub Release + +Create an annotated Git tag and push it to the main repository: + +```bash +# Tag the release +git tag -a vX.Y.Z -m "Release vX.Y.Z" +git push origin vX.Y.Z + +# For SDK specific releases +git tag -a sdk-vX.Y.Z -m "Release @signet/sdk vX.Y.Z" +git push origin sdk-vX.Y.Z +``` + +Create a GitHub Release describing the changes and referencing the tag. + +### Phase 4: Package & Contract Deployment + +1. **Publishing `@signet/sdk`**: + ```bash + pnpm --filter @signet/sdk publish --access public + ``` +2. **Deploying / Upgrading Contracts**: + - Follow the migration procedures in [`docs/CONTRACT_MIGRATION.md`](./CONTRACT_MIGRATION.md) and [`docs/DEPLOYMENT.md`](./DEPLOYMENT.md). + - Verify on-chain contract initialization (`initialize(admin)`). + - Update `NEXT_PUBLIC_IDENTITY_REGISTRY_ID` in production environment variables. + +--- + +## 4. Roles & Responsibilities + +- **Who Tags & Publishes**: Releases may only be tagged and published by repository maintainers (`@blockchain-maxis`). +- **Review Requirements**: Pull requests modifying contracts, auth systems, or release workflows require approvals designated in `.github/CODEOWNERS`. From 9c952ae29d079071bf019505f2873e42e7d3bd51 Mon Sep 17 00:00:00 2001 From: blockchain-maxis <267648998+blockchain-maxis@users.noreply.github.com> Date: Wed, 2 Sep 2026 12:16:04 +0100 Subject: [PATCH 2/2] docs: correct the testnet registry address and the untagged 0.1.0 heading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two things in CHANGELOG.md would have become wrong public references, which is the exact risk issue #227 opens with. The testnet identity-registry address was CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC, which appears nowhere else in the repo. The deployed registry — used by playwright.config.ts and e2e/testnet-claim.spec.ts — is CASFJHI5PQSRWS7JV25CF7FOMRKIVBP3RXRP3E2GH2CV4BCAG7FUJRCN. Both are live contracts on testnet, so a valid-looking address is not enough to tell them apart. Simulating the registry's own count() separates them: CASFJ… → count() = 2 CDLZF… → HostError: Error(Value, InvalidInput) so CDLZF… is some other contract that does not implement this interface. Dropped the invented 2026-07-09 deployment date with it. Also, [0.1.0] - 2026-08-28 claims a release that never happened: there are no git tags, and packages/sdk is at 0.0.0, while the RELEASING.md added in this same PR makes an annotated tag the marker of a release. Retitled to 'not yet tagged' with a note to date it when v0.1.0 is really cut. Prettier over the two new files; README's drift is pre-existing on main and left alone. node scripts/check-docs.mjs passes. --- CHANGELOG.md | 21 ++++++++++++++++----- docs/RELEASING.md | 14 +++++++------- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c5acb3..8ea7608 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,16 +11,17 @@ For release instructions and versioning procedures, see [`docs/RELEASING.md`](do ## Deployed Contract Registry -| Network | Contract | Contract ID | Deployed Date | Verification | -| --- | --- | --- | --- | --- | -| **Stellar Testnet** | `identity-registry` | `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC` | 2026-07-09 | Active (Soroban RPC) | -| **Stellar Mainnet** | `identity-registry` | *Pending deployment* | *TBD* | — | +| Network | Contract | Contract ID | Deployed Date | Verification | +| ------------------- | ------------------- | ---------------------------------------------------------- | ------------- | -------------------- | +| **Stellar Testnet** | `identity-registry` | `CASFJHI5PQSRWS7JV25CF7FOMRKIVBP3RXRP3E2GH2CV4BCAG7FUJRCN` | — | Active (Soroban RPC) | +| **Stellar Mainnet** | `identity-registry` | _Pending deployment_ | _TBD_ | — | --- ## [Unreleased] ### Added + - Area-based code review assignments via `.github/CODEOWNERS` ([#231](https://github.com/blockchain-maxis/signet/issues/231)). - CI concurrency group to cancel superseded in-progress workflow runs on push ([#229](https://github.com/blockchain-maxis/signet/issues/229)). - Release procedure documentation and versioning policy in `docs/RELEASING.md` ([#227](https://github.com/blockchain-maxis/signet/issues/227)). @@ -30,20 +31,30 @@ For release instructions and versioning procedures, see [`docs/RELEASING.md`](do - Live testnet E2E seam test for claim → resolve → profile flow ([#240](https://github.com/blockchain-maxis/signet/pull/240)). ### Changed + - Public SDK type surface stabilized ahead of `@signet/sdk@0.1.0` release ([#310](https://github.com/blockchain-maxis/signet/pull/310)). - Health route `/api/health` now reports nonce and rate-limit store status dynamically ([#309](https://github.com/blockchain-maxis/signet/pull/309)). - Connect wallet badge dynamically renders the active configured network from `NEXT_PUBLIC_STELLAR_NETWORK` ([#168](https://github.com/blockchain-maxis/signet/issues/168)). ### Fixed + - Added static `/handles` route to sitemap indexing ([#222](https://github.com/blockchain-maxis/signet/issues/222)). - Smoke tests now rely on semantic heading selectors instead of brittle copy assertions ([#219](https://github.com/blockchain-maxis/signet/issues/219)). - Extended contract instance TTL on read paths to prevent storage archival of active registries ([#242](https://github.com/blockchain-maxis/signet/pull/242)). --- -## [0.1.0] - 2026-08-28 +## [0.1.0] — not yet tagged + + ### Added + - Initial release of Signet developer career record platform. - **Identity Registry Contract** (`packages/contracts/identity-registry`): - On-chain handle claim, transfer, and release methods with owner authorization (`require_auth`). diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 6af1575..657f22a 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -16,13 +16,13 @@ PATCH (0.0.X) -> Backwards-compatible bug fixes, security patches, internal refa ### Monorepo Scope Breakdown -| Component | Scope | Version Reference | Version Impact | -| --- | --- | --- | --- | -| **`@signet/sdk`** | External TypeScript SDK | `packages/sdk/package.json` | Published to npm registry; breaking changes bump `MAJOR` | -| **`identity-registry`** | Soroban Rust contract | `packages/contracts/identity-registry/Cargo.toml` | On-chain bytecode deployed to permanent addresses; requires migration runbook if storage format changes | -| **`@signet/web`** | Next.js frontend & tRPC API | `apps/web/package.json` | Web application deployment; tracks overall platform release | -| **`@signet/indexer`** | Ingestion worker | `apps/indexer/package.json` | Background worker syncing events to Postgres | -| **`@signet/types`** | Shared type definitions | `packages/types/package.json` | Internal workspace dependency | +| Component | Scope | Version Reference | Version Impact | +| ----------------------- | --------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| **`@signet/sdk`** | External TypeScript SDK | `packages/sdk/package.json` | Published to npm registry; breaking changes bump `MAJOR` | +| **`identity-registry`** | Soroban Rust contract | `packages/contracts/identity-registry/Cargo.toml` | On-chain bytecode deployed to permanent addresses; requires migration runbook if storage format changes | +| **`@signet/web`** | Next.js frontend & tRPC API | `apps/web/package.json` | Web application deployment; tracks overall platform release | +| **`@signet/indexer`** | Ingestion worker | `apps/indexer/package.json` | Background worker syncing events to Postgres | +| **`@signet/types`** | Shared type definitions | `packages/types/package.json` | Internal workspace dependency | ---