From 46dcdd5be099f060940e02fbd2b66b911a5d0dd2 Mon Sep 17 00:00:00 2001 From: "brian.j.murdock@gmail.com" Date: Sat, 13 Jun 2026 23:54:36 -0500 Subject: [PATCH] Align public documentation with current release flow --- .github/pull_request_template.md | 3 +++ CHANGELOG.md | 3 +++ CONTRIBUTING.md | 6 ++++++ DESIGN.md | 9 ++++----- README.md | 6 +++++- RELEASE.md | 2 +- 6 files changed, 22 insertions(+), 7 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a33f107..244fc02 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -7,6 +7,9 @@ Describe the change and why it exists. - [ ] `npm run lint` - [ ] `npm test` - [ ] `npm run build` +- [ ] `npm run check:package-metadata` +- [ ] `npm run check:pack-smoke` +- [ ] dependency audit performed when dependencies or lockfiles change ## Notes diff --git a/CHANGELOG.md b/CHANGELOG.md index 88f0233..342e3ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ # Changelog +Entries describe repository versions. A version is publicly released only after +the matching `vX.Y.Z` tag publishes to npm and a GitHub Release exists. + ## 1.0.5 - add `redactHeaders()` for safe application-owned diagnostics without built-in logging diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae3879b..9711f40 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,10 +14,16 @@ Thanks for the interest in improving `clearfetch`. - `npm install` - `npm run lint` - `npm test` +- `npm run test:browser-like` - `npm run build` - `npm run check:package-metadata` - `npm run check:pack-smoke` +For dependency changes, also run the relevant audit command, usually: + +- `npm audit --registry=https://registry.npmjs.org` +- `npm audit --omit=dev --registry=https://registry.npmjs.org` + Changes should keep the public API, docs, tests, and runtime behavior aligned. ## Pull requests diff --git a/DESIGN.md b/DESIGN.md index 6b7eaec..a19ba92 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -286,14 +286,14 @@ The request lifecycle is defined as follows: 4. Build final headers 5. Normalize the request body 6. Execute `beforeRequest` hooks -7. Create the final `Request` -8. Apply timeout and abort configuration +7. Create the per-attempt timeout and abort signal +8. Create the final `Request` with the composed signal 9. Perform `fetch` 10. Execute `afterResponse` hooks 11. Classify non-success HTTP responses 12. Parse the response according to `responseType` 13. Return parsed result or raw `Response` -14. On failure, execute `onError` hooks with the classified failure context +14. On failure, execute `onError` hooks with the normalized or thrown failure context described below 15. Re-throw the classified failure This order is intentional and should remain stable unless there is a strong reason to change it. @@ -486,7 +486,7 @@ The package should not perform schema validation or content introspection beyond ### GET and HEAD bodies -As a general rule, bodies on `GET` and `HEAD` requests should be rejected or strongly constrained in v1. +Bodies on `GET` and `HEAD` requests are rejected in v1. Even though some systems tolerate them, they are unusual and frequently confusing. The package should prefer conservative behavior unless there is a compelling reason otherwise. @@ -1136,4 +1136,3 @@ The design should always favor: * trustworthiness over feature count That philosophy is the product. -``` diff --git a/README.md b/README.md index 307958b..b76c787 100644 --- a/README.md +++ b/README.md @@ -406,7 +406,11 @@ The public package surface is intentionally narrow: - `npm run check:pack-smoke`: smoke-test the packed tarball from a clean temporary install - `npm run lint`: run TypeScript static checks - `npm test`: run the test suite +- `npm run test:browser-like`: run browser-like package entrypoint coverage with `happy-dom` ## Status -`clearfetch` is published as `@gavoryn/clearfetch`. Project goals and behavior are documented in `PURPOSE.md` and `DESIGN.md`. +`clearfetch` is published as `@gavoryn/clearfetch`. The `main` branch may be +ahead of the latest npm package until a matching release tag runs the Release +workflow. Check npm and GitHub Releases for the currently published version. +Project goals and behavior are documented in `PURPOSE.md` and `DESIGN.md`. diff --git a/RELEASE.md b/RELEASE.md index 3cddd80..b52ab5d 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -35,7 +35,7 @@ That dry-run path should verify: - install, lint, test, and build steps - package metadata with `npm run check:package-metadata` - packed artifact behavior with `npm run check:pack-smoke` -- publishability with `npm publish --dry-run` +- publishability with `npm publish --dry-run --registry=https://registry.npmjs.org` Use the dry-run path before relying on a first release or after making workflow changes that affect packaging or publishing.