Skip to content

Commit 68aec18

Browse files
silentgeckoaudit3801silentgeckoaudit3801
committed
docs: refresh provenance release checklist link
1 parent f9ab9ae commit 68aec18

1 file changed

Lines changed: 299 additions & 21 deletions

File tree

‎docs/release-checklist.md‎

Lines changed: 299 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,323 @@
1-
# Release Checklist
1+
# SDK Release Readiness Checklist
22

3-
Follow these steps before publishing or tagging a new version of the SDK. Follow the [package provenance guide](./package-provenance.md) when changing publishing credentials, package metadata, or release automation.
3+
This checklist defines the required release gates for PocketPay SDK maintainers.
44

5-
## 1. Run the verification script
5+
A release must not be tagged or published until every applicable check is completed, any exception is documented, and a maintainer has approved the release.
66

7-
Run all pre-release checks (type-checking, tests, and build) in a single command:
7+
## Release record
8+
9+
Record the following information in the release pull request:
10+
11+
- **Release version:**
12+
- **Release type:** Patch / Minor / Major
13+
- **Release owner:**
14+
- **Target release date:**
15+
- **Release commit:**
16+
- **Migration note required:** Yes / No
17+
- **Security-sensitive changes:** Yes / No
18+
19+
## 1. Confirm the release scope
20+
21+
- [ ] Confirm that all intended changes are merged.
22+
- [ ] Confirm that unfinished or unrelated changes are excluded.
23+
- [ ] Confirm that the release branch has a clean working tree.
24+
- [ ] Confirm that the proposed version follows Semantic Versioning.
25+
- [ ] Identify all public API additions, changes, deprecations, and removals.
26+
- [ ] Identify any changes to supported runtimes, dependencies, configuration, or network behaviour.
27+
- [ ] Identify any security-sensitive changes.
28+
29+
Use the following versioning guidance:
30+
31+
| Release type | Use when |
32+
| ------------ | ------------------------------------------------------------------------------------ |
33+
| Patch | Backwards-compatible bug fixes, documentation corrections, and internal improvements |
34+
| Minor | Backwards-compatible public API additions and deprecations |
35+
| Major | Breaking API, runtime, configuration, behaviour, or security-contract changes |
36+
37+
## 2. Install locked dependencies
38+
39+
Use the committed lockfile so release verification runs against the expected dependency versions:
40+
41+
```bash
42+
npm ci
43+
```
44+
45+
- [ ] Dependency installation completes successfully.
46+
- [ ] No unexpected changes are made to `package-lock.json`.
47+
- [ ] No unreviewed dependency is introduced.
48+
49+
## 3. Run automated verification
50+
51+
Run the complete verification command:
852

953
```bash
1054
npm run verify
1155
```
1256

13-
This runs the following in sequence:
57+
This executes:
58+
59+
| Check | Command | Expected result |
60+
| ------------------------- | ------------------------ | ----------------------------------- |
61+
| Type checking | `npm run lint` | No TypeScript errors |
62+
| Circular dependency check | `npm run check:circular` | No prohibited circular dependencies |
63+
| Unit tests | `npm run test` | All tests pass |
64+
| Package build | `npm run build` | The SDK builds successfully |
65+
66+
Where the release changes integration behaviour, also run:
67+
68+
```bash
69+
npm run test:integration
70+
```
71+
72+
Where the release changes published exports or build output, run:
73+
74+
```bash
75+
npm run test:smoke
76+
npm pack --dry-run
77+
```
78+
79+
- [ ] `npm run verify` passes.
80+
- [ ] Applicable integration tests pass.
81+
- [ ] Applicable smoke tests pass.
82+
- [ ] New and changed behaviour has appropriate test coverage.
83+
- [ ] The package preview contains only intended publishable files.
84+
- [ ] Generated declaration files reflect the intended public API.
85+
86+
## 4. Review the public API
87+
88+
The supported public API is defined by:
89+
90+
- exports from `src/index.ts`;
91+
- package entry points in the `exports` field of `package.json`;
92+
- generated TypeScript declarations under `dist/`;
93+
- documented SDK behaviour.
94+
95+
Review the release for:
96+
97+
- [ ] New exported functions, classes, constants, or types.
98+
- [ ] Removed or renamed exports.
99+
- [ ] Changed function parameters.
100+
- [ ] Changed return types.
101+
- [ ] Changed required or optional object properties.
102+
- [ ] Changed default values.
103+
- [ ] Changed error codes or error behaviour.
104+
- [ ] Changed validation, retry, timeout, or network behaviour.
105+
- [ ] Changed runtime or dependency requirements.
106+
- [ ] Accidental exports of internal implementation details.
107+
- [ ] Deep-import examples that should use package-root imports.
108+
109+
Any breaking public API change requires:
110+
111+
1. a major-version release;
112+
2. an entry in `CHANGELOG.md`;
113+
3. a migration guide based on the migration-note template;
114+
4. updated API documentation and examples;
115+
5. explicit maintainer approval.
116+
117+
See [SDK Migration System](./sdk_migration_system.md).
118+
119+
## 5. Complete the security review
120+
121+
A security review is required for changes involving:
122+
123+
- wallet creation, import, recovery, or secret handling;
124+
- transaction construction, signing, simulation, or submission;
125+
- Horizon, Friendbot, or Soroban RPC communication;
126+
- environment variables or SDK configuration;
127+
- account, asset, amount, contract, or destination validation;
128+
- logs, debugging information, or error payloads;
129+
- retry, idempotency, timeout, or network-failure behaviour;
130+
- new or updated dependencies.
131+
132+
Complete the checks in [SDK Security Readiness Review](./sdk_security_readiness_review.md).
133+
134+
At minimum, confirm:
135+
136+
- [ ] No secret keys, seed phrases, credentials, tokens, or `.env` files are included.
137+
- [ ] Sensitive values cannot appear in logs or public errors.
138+
- [ ] Package provenance and publishing-integrity guidance in [Package Provenance](./package-provenance.md) has been reviewed for any publishing or release automation changes.
139+
- [ ] Security-sensitive inputs are validated.
140+
- [ ] Network and transaction assumptions are documented.
141+
- [ ] Dependency additions or updates have been reviewed.
142+
- [ ] Security-sensitive behaviour has focused tests.
143+
- [ ] Security-impacting migration guidance is included.
144+
- [ ] No unresolved security concern remains.
145+
146+
An unresolved security concern blocks the release.
147+
148+
## 6. Review documentation and examples
149+
150+
- [ ] README guidance remains accurate.
151+
- [ ] Public API documentation matches the released implementation.
152+
- [ ] Configuration and runtime requirements are documented.
153+
- [ ] Examples use supported package-root imports.
154+
- [ ] New features include usage examples.
155+
- [ ] Deprecated APIs include replacement guidance.
156+
- [ ] Breaking changes include before-and-after examples.
157+
- [ ] Removed APIs are no longer presented as supported.
158+
- [ ] Security guidance reflects the released behaviour.
159+
- [ ] Documentation links resolve to valid files and headings.
160+
161+
## 7. Update the changelog
162+
163+
Follow the [Changelog Policy](./changelog-policy.md).
164+
165+
Add all user-visible changes under `## [Unreleased]` using the appropriate categories:
166+
167+
- `Added`
168+
169+
- `Changed`
170+
171+
- `Deprecated`
172+
173+
- `Removed`
174+
175+
- `Fixed`
176+
177+
- `Security`
178+
179+
- [ ] Entries describe consumer impact rather than internal implementation details.
180+
181+
- [ ] Breaking changes are clearly identified.
182+
183+
- [ ] Security-relevant changes are listed under `Security`.
184+
185+
- [ ] Deprecations identify the supported replacement.
186+
187+
- [ ] Related migration guides are linked.
188+
189+
- [ ] The changelog matches the selected Semantic Versioning level.
190+
191+
## 8. Prepare migration guidance
192+
193+
A migration guide is required when consumers must change:
194+
195+
- imports or application source code;
196+
- configuration or environment variables;
197+
- runtime or dependency versions;
198+
- validation or error-handling logic;
199+
- wallet, signing, or secret-storage behaviour;
200+
- deployment or operational procedures.
201+
202+
Create migration guidance from:
203+
204+
```text
205+
docs/migration-note-template.md
206+
```
207+
208+
Store completed migration guides as:
209+
210+
```text
211+
docs/migrations/<version>.md
212+
```
213+
214+
For example:
215+
216+
```text
217+
docs/migrations/2.0.0.md
218+
```
219+
220+
- [ ] The affected consumer group is identified.
221+
- [ ] Required actions are presented in order.
222+
- [ ] Before-and-after examples are included.
223+
- [ ] Runtime and configuration changes are documented.
224+
- [ ] Security implications are documented.
225+
- [ ] Rollback or temporary compatibility options are described.
226+
- [ ] The migration guide is linked from the changelog.
227+
228+
See [SDK Migration System](./sdk_migration_system.md).
229+
230+
## 9. Record release-readiness evidence
14231

15-
| Step | Command | What it checks |
16-
|------|---------|----------------|
17-
| Type-check | `npm run lint` | No TypeScript errors (`tsc --noEmit`) |
18-
| Tests | `npm run test` | All Vitest tests pass |
19-
| Build | `npm run build` | `dist/` compiles cleanly with `tsc` |
232+
The release pull request must include evidence for each applicable gate:
20233

21-
All three steps must pass before proceeding.
234+
| Gate | Required evidence | Approved |
235+
| ---------------------- | --------------------------------------------------------------------- | -------- |
236+
| Automated verification | CI results or command output | [ ] |
237+
| Public API review | Summary of additions, changes, removals, or confirmation of no change | [ ] |
238+
| Security review | Completed review or documented reason it is not applicable | [ ] |
239+
| Documentation review | Updated documentation and examples | [ ] |
240+
| Changelog review | Changelog entry | [ ] |
241+
| Migration review | Migration guide or documented reason it is not required | [ ] |
22242

23-
## 2. Review the changelog
243+
At least one maintainer must confirm that the release evidence is complete.
24244

25-
- Confirm the version bump in `package.json` matches the intended semver level (patch / minor / major).
26-
- Ensure `CHANGELOG.md` (if maintained) is up to date.
245+
## 10. Prepare the release version
27246

28-
## 3. Tag the release
247+
Update the package version using the appropriate Semantic Versioning level:
29248

30249
```bash
31-
git tag v<version>
32-
git push origin v<version>
250+
npm version patch --no-git-tag-version
251+
```
252+
253+
Replace `patch` with `minor` or `major` where appropriate.
254+
255+
Review the version changes:
256+
257+
```bash
258+
git diff -- package.json package-lock.json
33259
```
34260

35-
Replace `<version>` with the value in `package.json` (e.g., `1.1.0`).
261+
- [ ] `package.json` contains the intended version.
262+
- [ ] `package-lock.json` contains the same version.
263+
- [ ] No unrelated package metadata changed.
264+
265+
Run final verification after the version update:
266+
267+
```bash
268+
npm run verify
269+
npm pack --dry-run
270+
```
36271

37-
## 4. Publish to npm
272+
## 11. Tag and publish
38273

39-
Publishing triggers `prepublishOnly`, which runs `npm run build` again as a final safety net:
274+
Only perform these steps after the release pull request has been approved and merged:
40275

41276
```bash
277+
git switch main
278+
git pull --ff-only
279+
git tag v<version>
280+
git push origin v<version>
42281
npm publish
43282
```
44283

45-
> **Note:** This is not an automated publish workflow. Each step above is a manual check performed by the maintainer.
284+
Replace `<version>` with the exact version from `package.json`.
285+
286+
- [ ] The tag points to the approved release commit.
287+
- [ ] The published npm version matches the Git tag.
288+
- [ ] The package was published from a clean checkout.
289+
- [ ] Publishing credentials were handled securely.
290+
291+
## 12. Perform post-release verification
292+
293+
- [ ] Confirm that npm displays the intended version.
294+
- [ ] Confirm that the Git tag points to the released commit.
295+
- [ ] Install the published package in a clean temporary project.
296+
- [ ] Confirm that package-root imports work.
297+
- [ ] Run a basic SDK smoke test.
298+
- [ ] Confirm that release notes link to the changelog.
299+
- [ ] Confirm that any required migration guide is linked.
300+
- [ ] Announce required consumer actions.
301+
302+
## 13. Handle a failed release
303+
304+
If a release is incorrect or unsafe:
305+
306+
1. stop further promotion or announcements;
307+
2. document the affected version and impact;
308+
3. prepare a corrective release;
309+
4. deprecate the affected npm version where appropriate;
310+
5. do not overwrite or reuse a published version number;
311+
6. add remediation instructions to the changelog and migration documentation.
312+
313+
A release with unresolved API, security, testing, documentation, or migration concerns is not release-ready.
314+
315+
## Related documentation
316+
317+
- [SDK Migration System](./sdk_migration_system.md)
318+
- [Migration Note Template](./migration-note-template.md)
319+
- [Changelog Policy](./changelog-policy.md)
320+
- [SDK Security Readiness Review](./sdk_security_readiness_review.md)
321+
- [API Reference](./api-reference.md)
322+
- [Security Guidance](./security.md)
323+
- [Support Policy](./support-policy.md)

0 commit comments

Comments
 (0)