Skip to content

Commit 1913397

Browse files
TDanks2000TDanks2000
committed
docs: improve trust and release setup
1 parent 526737b commit 1913397

16 files changed

Lines changed: 1180 additions & 79 deletions

‎.changeset/config.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
3+
"changelog": "@changesets/cli/changelog",
4+
"commit": false,
5+
"fixed": [],
6+
"linked": [],
7+
"access": "public",
8+
"baseBranch": "main",
9+
"updateInternalDependencies": "patch",
10+
"ignore": []
11+
}

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: Bug report
2+
description: Report a reproducible problem in api-core
3+
title: "bug: "
4+
labels:
5+
- bug
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Thanks for reporting a bug. Please include enough detail for someone to reproduce the behavior without access to your local project.
11+
- type: textarea
12+
id: summary
13+
attributes:
14+
label: Summary
15+
description: What went wrong?
16+
placeholder: A clear description of the problem.
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: reproduction
21+
attributes:
22+
label: Reproduction
23+
description: Provide a minimal example, test case, or repository link.
24+
placeholder: |
25+
1. Create a client with ...
26+
2. Call ...
27+
3. Observe ...
28+
validations:
29+
required: true
30+
- type: textarea
31+
id: expected
32+
attributes:
33+
label: Expected behavior
34+
description: What did you expect to happen?
35+
validations:
36+
required: true
37+
- type: textarea
38+
id: actual
39+
attributes:
40+
label: Actual behavior
41+
description: What happened instead? Include stack traces or response details when relevant.
42+
validations:
43+
required: true
44+
- type: input
45+
id: version
46+
attributes:
47+
label: api-core version
48+
placeholder: "1.0.2"
49+
validations:
50+
required: true
51+
- type: dropdown
52+
id: runtime
53+
attributes:
54+
label: Runtime
55+
options:
56+
- Bun
57+
- Node.js
58+
- Browser
59+
- Edge runtime
60+
- Other
61+
validations:
62+
required: true
63+
- type: input
64+
id: runtime-version
65+
attributes:
66+
label: Runtime version
67+
placeholder: "Bun 1.3.13, Node 22.x, browser/version, etc."
68+
- type: textarea
69+
id: config
70+
attributes:
71+
label: Client configuration
72+
description: Share relevant `createClient` options, plugins, retry config, transport config, or custom fetch setup.
73+
render: ts
74+
- type: textarea
75+
id: validation
76+
attributes:
77+
label: Validation
78+
description: What commands did you run?
79+
placeholder: |
80+
bun install
81+
bun run verify
82+
- type: checkboxes
83+
id: checks
84+
attributes:
85+
label: Checklist
86+
options:
87+
- label: I checked for an existing issue.
88+
required: true
89+
- label: I can reproduce this with the latest available version.
90+
required: true
91+
- label: I included a minimal reproduction or enough code to reproduce the issue.
92+
required: true

‎.github/ISSUE_TEMPLATE/docs_request.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Documentation request
2+
description: Request clearer or missing api-core documentation
3+
title: "docs: "
4+
labels:
5+
- documentation
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Thanks for improving the docs. Please describe what was confusing, missing, or hard to apply.
11+
- type: textarea
12+
id: page
13+
attributes:
14+
label: Page or section
15+
description: Link to the README, guide, API reference, or section that needs work.
16+
placeholder: README examples, docs/guides/plugins.md, docs/reference/client.md, etc.
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: problem
21+
attributes:
22+
label: What is confusing or missing?
23+
description: Explain the documentation gap from a reader's point of view.
24+
validations:
25+
required: true
26+
- type: textarea
27+
id: suggested
28+
attributes:
29+
label: Suggested improvement
30+
description: What example, explanation, link, or reference detail would help?
31+
- type: dropdown
32+
id: audience
33+
attributes:
34+
label: Reader type
35+
options:
36+
- Wrapper package maintainer
37+
- Direct api-core user
38+
- New contributor
39+
- Other
40+
validations:
41+
required: true
42+
- type: checkboxes
43+
id: checks
44+
attributes:
45+
label: Checklist
46+
options:
47+
- label: I checked the README and docs directory for existing coverage.
48+
required: true
49+
- label: This is a documentation request, not a runtime feature request.
50+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Feature request
2+
description: Suggest an improvement for api-core
3+
title: "feat: "
4+
labels:
5+
- enhancement
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Thanks for suggesting an improvement. api-core stays small on purpose, so feature requests should explain which wrapper packages or direct users benefit.
11+
- type: textarea
12+
id: problem
13+
attributes:
14+
label: Problem
15+
description: What problem should this solve?
16+
placeholder: Describe the wrapper or runtime need.
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: proposal
21+
attributes:
22+
label: Proposed solution
23+
description: What API, docs, plugin, or behavior would you add or change?
24+
validations:
25+
required: true
26+
- type: textarea
27+
id: alternatives
28+
attributes:
29+
label: Alternatives considered
30+
description: What can users do today, and why is it not enough?
31+
- type: dropdown
32+
id: area
33+
attributes:
34+
label: Area
35+
options:
36+
- Runtime client
37+
- Plugin lifecycle
38+
- Built-in plugin
39+
- Transport or custom fetch
40+
- GraphQL
41+
- Errors and type guards
42+
- Documentation
43+
- Build or package output
44+
- Other
45+
validations:
46+
required: true
47+
- type: textarea
48+
id: api
49+
attributes:
50+
label: API sketch
51+
description: If this changes public API, show the TypeScript shape or example usage.
52+
render: ts
53+
- type: textarea
54+
id: users
55+
attributes:
56+
label: Who benefits?
57+
description: Which Api-Wrappers packages, wrapper authors, or direct users would use this?
58+
validations:
59+
required: true
60+
- type: checkboxes
61+
id: checks
62+
attributes:
63+
label: Checklist
64+
options:
65+
- label: I checked for an existing feature request.
66+
required: true
67+
- label: I explained why this belongs in api-core instead of a provider-specific wrapper.
68+
required: true
69+
- label: I considered documentation and test coverage for the change.
70+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## Summary
2+
3+
<!-- What changed and why? -->
4+
5+
## Type of change
6+
7+
- [ ] Documentation
8+
- [ ] Bug fix
9+
- [ ] New runtime feature
10+
- [ ] Built-in plugin change
11+
- [ ] Build or package metadata
12+
- [ ] Other
13+
14+
## Public API impact
15+
16+
- [ ] No public runtime API changes
17+
- [ ] Public API added
18+
- [ ] Public API changed
19+
- [ ] Public API removed
20+
21+
If the public API changed, describe the migration path:
22+
23+
## Validation
24+
25+
- [ ] `bun install`
26+
- [ ] `bun run verify`
27+
- [ ] Other:
28+
29+
## Checklist
30+
31+
- [ ] I kept strict TypeScript and did not use `any`.
32+
- [ ] I added or updated tests for runtime behavior changes.
33+
- [ ] I added or updated docs for user-facing behavior changes.
34+
- [ ] I considered Bun, Node, browser, and edge runtime compatibility.
35+
- [ ] I kept provider-specific behavior out of `api-core`.

‎.github/RELEASE.md‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# Release Workflow
22

3-
Releases are published by `.github/workflows/release.yml` when a semver tag is
4-
pushed, for example `v1.2.3`.
3+
Releases are managed with Changesets and `.github/workflows/release.yml`.
4+
Publishing only runs from `main`; pull requests never publish.
55

66
## npm Trusted Publishing
77

8-
The release workflow is designed for npm Trusted Publishing with OIDC. It does
9-
not use `NPM_TOKEN`.
8+
The release workflow is designed for npm Trusted Publishing with OIDC and npm
9+
provenance. It does not require `NPM_TOKEN` when trusted publishing is
10+
configured.
1011

1112
Configure the package on npmjs.com:
1213

@@ -18,25 +19,30 @@ Configure the package on npmjs.com:
1819
6. After a successful trusted publish, set publishing access to require 2FA and
1920
disallow traditional tokens.
2021

21-
The workflow grants `id-token: write`, uses Node.js 24, and verifies the npm CLI
22-
is at least `11.5.1`, matching npm's trusted publishing requirements.
23-
GitHub Actions are pinned to current release tags rather than deprecated major
22+
The workflow grants `id-token: write`, uses Node.js 24, verifies the npm CLI is
23+
at least `11.5.1`, and publishes with `npm publish --provenance`. GitHub
24+
Actions are pinned to current release tags rather than deprecated major
2425
versions. Dependabot is configured to keep workflow action pins current.
2526

27+
If trusted publishing is not available, use `NPM_TOKEN` as the repository secret
28+
name and wire it to `NODE_AUTH_TOKEN` before publishing.
29+
2630
## Release Steps
2731

28-
1. Update `package.json` version.
29-
2. Commit the version change.
30-
3. Create and push a matching tag:
32+
1. Add a changeset for user-facing changes:
3133

3234
```bash
33-
git tag v1.2.3
34-
git push origin v1.2.3
35+
bun run changeset
3536
```
3637

37-
The workflow checks that `package.json` version matches the tag without the
38-
leading `v`, runs lint/tests/build, verifies package contents, publishes to npm,
39-
and creates a GitHub release with generated notes.
38+
2. Merge the change to `main`.
39+
3. The release workflow validates the package and opens a Changesets version PR.
40+
4. Review and merge the version PR.
41+
5. The next `main` run validates again, publishes to npm with provenance, and
42+
creates GitHub release notes.
43+
44+
Maintainers can manually run the release workflow with `dry_run: true` to verify
45+
the install, validation, and package dry-run steps without publishing.
4046

4147
## CI Workflow
4248

0 commit comments

Comments
 (0)