Skip to content

Commit e308901

Browse files
rgbkrkrgbkrk
committed
push it up
1 parent 7ec384e commit e308901

File tree

3 files changed

+505
-0
lines changed

3 files changed

+505
-0
lines changed

‎docs/schema-publishing.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# Schema Package Publishing
2+
3+
This document explains how to publish the `@runtimed/schema` package to both npm and JSR.
4+
5+
## Overview
6+
7+
The `@runtimed/schema` package is published to two registries:
8+
- **npm**: https://www.npmjs.com/package/@runtimed/schema
9+
- **JSR**: https://jsr.io/@runtimed/schema
10+
11+
Both registries are kept in sync with matching version numbers.
12+
13+
## Prerequisites
14+
15+
### For Automated Publishing (GitHub Actions)
16+
17+
1. **NPM_TOKEN**: npm access token with publish permissions
18+
- Generate at: https://www.npmjs.com/settings/tokens
19+
- Add to GitHub repository secrets
20+
21+
2. **JSR_TOKEN**: JSR access token with publish permissions
22+
- Generate at: https://jsr.io/account/tokens
23+
- Add to GitHub repository secrets
24+
25+
### For Manual Publishing
26+
27+
1. **npm**: Authenticated with `npm login`
28+
2. **JSR**: JSR CLI installed (`npm install -g jsr`)
29+
30+
## Automated Publishing (Recommended)
31+
32+
Publishing is automated via GitHub Actions when you push a git tag:
33+
34+
### 1. Update Version
35+
36+
Use the provided script to update both `package.json` and `jsr.json`:
37+
38+
```bash
39+
# Bump to a new version (e.g., 0.1.3)
40+
pnpm bump-schema 0.1.3
41+
```
42+
43+
This script:
44+
- Updates version in both `package.json` and `jsr.json`
45+
- Validates version format
46+
- Stages changes for git commit
47+
48+
### 2. Test Locally
49+
50+
Before publishing, test that everything works:
51+
52+
```bash
53+
pnpm test-publish
54+
```
55+
56+
This runs:
57+
- Version consistency check
58+
- Type checking
59+
- Linting
60+
- Format checking
61+
- Dry run publishing to both registries
62+
63+
### 3. Commit and Tag
64+
65+
```bash
66+
git commit -m "Bump schema version to v0.1.3"
67+
git tag v0.1.3
68+
git push origin HEAD --tags
69+
```
70+
71+
### 4. GitHub Actions Takes Over
72+
73+
The workflow (`.github/workflows/publish.yml`) automatically:
74+
1. Validates version consistency
75+
2. Runs all checks (type, lint, format)
76+
3. Tests dry run publishing
77+
4. Publishes to npm
78+
5. Publishes to JSR
79+
6. Creates GitHub release
80+
81+
## Manual Publishing
82+
83+
If you need to publish manually:
84+
85+
### 1. Prepare and Test
86+
87+
```bash
88+
# Update versions
89+
pnpm bump-schema 0.1.3
90+
91+
# Test everything
92+
pnpm test-publish
93+
```
94+
95+
### 2. Publish to npm
96+
97+
```bash
98+
pnpm --filter schema publish --access public --no-git-checks
99+
```
100+
101+
### 3. Publish to JSR
102+
103+
```bash
104+
pnpm --filter schema exec jsr publish --allow-slow-types
105+
```
106+
107+
## Workflow Details
108+
109+
### Version Management
110+
111+
- Both `package.json` and `jsr.json` must have matching version numbers
112+
- Use semantic versioning (e.g., `0.1.3`, `1.0.0`, `2.1.0-beta.1`)
113+
- The `bump-schema` script ensures consistency
114+
115+
### Validation Steps
116+
117+
The publishing process includes several validation steps:
118+
119+
1. **Version Consistency**: Both files have matching versions
120+
2. **Tag Validation**: Git tag matches package version
121+
3. **Type Check**: TypeScript compilation without errors
122+
4. **Lint Check**: ESLint passes with no warnings
123+
5. **Format Check**: Prettier formatting is correct
124+
6. **Publish Dry Run**: Both registries accept the package
125+
126+
### Publishing Strategy
127+
128+
- **Tags trigger publishing**: Only git tags starting with `v` trigger the workflow
129+
- **Both registries**: Package is published to npm and JSR simultaneously
130+
- **Failure handling**: If either registry fails, the workflow stops
131+
- **GitHub Release**: Automatically created with links to both registries
132+
133+
## Troubleshooting
134+
135+
### Version Mismatch
136+
137+
```bash
138+
❌ Version mismatch: package.json (0.1.2) != jsr.json (0.1.1)
139+
```
140+
141+
**Solution**: Use `pnpm bump-schema <version>` to sync versions.
142+
143+
### JSR Slow Types Warning
144+
145+
```
146+
Warning Publishing a library with slow types is not recommended.
147+
```
148+
149+
This is expected. The schema package uses complex TypeScript types that JSR considers "slow types". We use `--allow-slow-types` to publish anyway.
150+
151+
### npm Authentication
152+
153+
```bash
154+
npm error code ENEEDAUTH
155+
```
156+
157+
**Solution**: Run `npm login` or ensure `NPM_TOKEN` is set correctly.
158+
159+
### JSR Authentication
160+
161+
```bash
162+
error: Unauthorized
163+
```
164+
165+
**Solution**: Ensure `JSR_TOKEN` is set correctly in GitHub secrets or run `jsr auth` for manual publishing.
166+
167+
### Git Tag Issues
168+
169+
```bash
170+
❌ Tag version (0.1.3) doesn't match package version (0.1.2)
171+
```
172+
173+
**Solution**: Ensure you've committed the version bump before tagging, or update the tag to match the package version.
174+
175+
## Scripts Reference
176+
177+
| Script | Command | Purpose |
178+
|--------|---------|---------|
179+
| Version Bump | `pnpm bump-schema <version>` | Update package versions consistently |
180+
| Test Publish | `pnpm test-publish` | Validate everything before publishing |
181+
| Manual npm | `pnpm --filter schema publish --access public` | Publish to npm only |
182+
| Manual JSR | `pnpm --filter schema exec jsr publish --allow-slow-types` | Publish to JSR only |
183+
184+
## Package Structure
185+
186+
```
187+
packages/schema/
188+
├── package.json # npm package configuration
189+
├── jsr.json # JSR package configuration
190+
├── README.md # Package documentation
191+
├── src/
192+
│ ├── index.ts # Main export
193+
│ ├── tables.ts # Database schema
194+
│ ├── types.ts # TypeScript types
195+
│ └── queries/ # Query helpers
196+
└── tsconfig.json # TypeScript configuration
197+
```
198+
199+
## Release Checklist
200+
201+
- [ ] Version numbers match in `package.json` and `jsr.json`
202+
- [ ] `pnpm test-publish` passes all checks
203+
- [ ] Changes committed to git
204+
- [ ] Git tag created and pushed
205+
- [ ] GitHub Actions workflow completes successfully
206+
- [ ] Both npm and JSR packages are live
207+
- [ ] GitHub release is created
208+
209+
## Support
210+
211+
For issues with the publishing process:
212+
1. Check GitHub Actions logs for detailed error messages
213+
2. Test locally with `pnpm test-publish`
214+
3. Verify authentication tokens are valid
215+
4. Ensure version numbers are consistent

‎scripts/bump-schema-version.sh‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
#!/bin/bash
2+
set -e
3+
4+
# Colors for output
5+
RED='\033[0;31m'
6+
GREEN='\033[0;32m'
7+
YELLOW='\033[1;33m'
8+
BLUE='\033[0;34m'
9+
NC='\033[0m' # No Color
10+
11+
# Function to print colored output
12+
print_status() {
13+
echo -e "${BLUE}[INFO]${NC} $1"
14+
}
15+
16+
print_success() {
17+
echo -e "${GREEN}[SUCCESS]${NC} $1"
18+
}
19+
20+
print_warning() {
21+
echo -e "${YELLOW}[WARNING]${NC} $1"
22+
}
23+
24+
print_error() {
25+
echo -e "${RED}[ERROR]${NC} $1"
26+
}
27+
28+
# Check if version argument is provided
29+
if [ $# -eq 0 ]; then
30+
print_error "Usage: $0 <version>"
31+
print_error "Example: $0 0.1.3"
32+
exit 1
33+
fi
34+
35+
NEW_VERSION="$1"
36+
SCHEMA_DIR="packages/schema"
37+
PACKAGE_JSON="$SCHEMA_DIR/package.json"
38+
JSR_JSON="$SCHEMA_DIR/jsr.json"
39+
40+
# Validate version format (basic semver check)
41+
if ! echo "$NEW_VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$'; then
42+
print_error "Invalid version format: $NEW_VERSION"
43+
print_error "Expected format: X.Y.Z (semver)"
44+
exit 1
45+
fi
46+
47+
print_status "Bumping schema package version to $NEW_VERSION"
48+
49+
# Check if we're in the right directory
50+
if [ ! -f "$PACKAGE_JSON" ]; then
51+
print_error "package.json not found at $PACKAGE_JSON"
52+
print_error "Make sure you're running this from the anode root directory"
53+
exit 1
54+
fi
55+
56+
if [ ! -f "$JSR_JSON" ]; then
57+
print_error "jsr.json not found at $JSR_JSON"
58+
exit 1
59+
fi
60+
61+
# Get current versions
62+
CURRENT_PACKAGE_VERSION=$(node -p "require('./$PACKAGE_JSON').version" 2>/dev/null || echo "unknown")
63+
CURRENT_JSR_VERSION=$(node -p "require('./$JSR_JSON').version" 2>/dev/null || echo "unknown")
64+
65+
print_status "Current package.json version: $CURRENT_PACKAGE_VERSION"
66+
print_status "Current jsr.json version: $CURRENT_JSR_VERSION"
67+
68+
# Check if versions are currently in sync
69+
if [ "$CURRENT_PACKAGE_VERSION" != "$CURRENT_JSR_VERSION" ]; then
70+
print_warning "Current versions are out of sync!"
71+
fi
72+
73+
# Update package.json
74+
print_status "Updating $PACKAGE_JSON..."
75+
if command -v jq >/dev/null 2>&1; then
76+
# Use jq if available (preferred)
77+
jq ".version = \"$NEW_VERSION\"" "$PACKAGE_JSON" > "${PACKAGE_JSON}.tmp" && mv "${PACKAGE_JSON}.tmp" "$PACKAGE_JSON"
78+
else
79+
# Fallback to sed
80+
if [[ "$OSTYPE" == "darwin"* ]]; then
81+
# macOS
82+
sed -i '' "s/\"version\": \".*\"/\"version\": \"$NEW_VERSION\"/" "$PACKAGE_JSON"
83+
else
84+
# Linux
85+
sed -i "s/\"version\": \".*\"/\"version\": \"$NEW_VERSION\"/" "$PACKAGE_JSON"
86+
fi
87+
fi
88+
89+
# Update jsr.json
90+
print_status "Updating $JSR_JSON..."
91+
if command -v jq >/dev/null 2>&1; then
92+
# Use jq if available (preferred)
93+
jq ".version = \"$NEW_VERSION\"" "$JSR_JSON" > "${JSR_JSON}.tmp" && mv "${JSR_JSON}.tmp" "$JSR_JSON"
94+
else
95+
# Fallback to sed
96+
if [[ "$OSTYPE" == "darwin"* ]]; then
97+
# macOS
98+
sed -i '' "s/\"version\": \".*\"/\"version\": \"$NEW_VERSION\"/" "$JSR_JSON"
99+
else
100+
# Linux
101+
sed -i "s/\"version\": \".*\"/\"version\": \"$NEW_VERSION\"/" "$JSR_JSON"
102+
fi
103+
fi
104+
105+
# Verify the changes
106+
UPDATED_PACKAGE_VERSION=$(node -p "require('./$PACKAGE_JSON').version")
107+
UPDATED_JSR_VERSION=$(node -p "require('./$JSR_JSON').version")
108+
109+
if [ "$UPDATED_PACKAGE_VERSION" != "$NEW_VERSION" ] || [ "$UPDATED_JSR_VERSION" != "$NEW_VERSION" ]; then
110+
print_error "Failed to update versions correctly"
111+
print_error "package.json: $UPDATED_PACKAGE_VERSION"
112+
print_error "jsr.json: $UPDATED_JSR_VERSION"
113+
exit 1
114+
fi
115+
116+
print_success "Successfully updated both files to version $NEW_VERSION"
117+
118+
# Stage the changes
119+
if git status >/dev/null 2>&1; then
120+
print_status "Staging changes..."
121+
git add "$PACKAGE_JSON" "$JSR_JSON"
122+
123+
print_status "Changes staged. You can now commit with:"
124+
echo "git commit -m \"Bump schema version to v$NEW_VERSION\""
125+
echo "git tag v$NEW_VERSION"
126+
echo "git push origin HEAD --tags"
127+
print_warning "Remember: Pushing the tag will trigger the publish workflow!"
128+
else
129+
print_warning "Not in a git repository. Changes made but not staged."
130+
fi
131+
132+
# Show what changed
133+
print_status "Summary of changes:"
134+
echo " $PACKAGE_JSON: $CURRENT_PACKAGE_VERSION → $NEW_VERSION"
135+
echo " $JSR_JSON: $CURRENT_JSR_VERSION → $NEW_VERSION"
136+
137+
print_success "Version bump complete!"

0 commit comments

Comments
 (0)