Skip to content

Commit 0433a0d

Browse files
Ankur2019Ankur2019
authored
Merge pull request #2 from Encryptioner/pre/release/1.0.0
Pre/release/1.0.0
2 parents 20f83e7 + 253db80 commit 0433a0d

7 files changed

Lines changed: 378 additions & 12 deletions

File tree

‎.github/PUBLISHING.md‎

Lines changed: 64 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,7 @@ git push origin master
352352
git push origin v1.1.0
353353

354354
# 7. Monitor GitHub Actions
355-
# Go to: https://github.com/encryptioner/html-to-pdf-generator/actions
355+
# Go to: https://github.com/Encryptioner/html-to-pdf-generator/actions
356356
# Watch the "Publish to NPM" workflow
357357

358358
# 8. Verify publication
@@ -570,16 +570,74 @@ pnpm version 1.0.2
570570
git push origin v1.0.2
571571
```
572572

573+
**If you need to move a tag to a different commit:**
574+
575+
This happens when you create a tag, then make additional commits (like bug fixes) and want the tag to point to the latest commit.
576+
577+
```bash
578+
# Scenario: You created tag v1.0.0, then made fixes, now want to move the tag
579+
580+
# 1. Commit your fixes first
581+
git add .
582+
git commit -m "fix: your fix message"
583+
git push origin pre/release/1.0.0 # or your branch
584+
585+
# 2. Delete the old tag locally
586+
git tag -d v1.0.0
587+
588+
# 3. Delete the old tag from remote (this cancels any running workflow)
589+
git push origin --delete v1.0.0
590+
591+
# 4. Create the tag again on the current commit
592+
git tag v1.0.0
593+
594+
# 5. Force push the new tag
595+
git push origin v1.0.0
596+
597+
# Alternative: Use --force flag in one step
598+
git tag -f v1.0.0 # Force create/move tag locally
599+
git push origin v1.0.0 --force # Force push to remote
600+
```
601+
602+
**Important Notes:**
603+
- Always commit and push your code changes BEFORE creating/moving tags
604+
- Moving a tag will restart the publish workflow from the beginning
605+
- The package.json version must match the tag version (e.g., v1.0.0 → "version": "1.0.0")
606+
573607
**If the workflow fails after pushing a tag:**
574608
1. Check the GitHub Actions logs for the error
575609
2. Fix the issue in your code
576-
3. Delete the failed tag (see above)
577-
4. Create a new patch version tag
578-
5. Push the new tag
610+
3. Commit and push the fixes
611+
4. Move the tag to the new commit (see above)
612+
OR delete the tag and create a new patch version
613+
614+
**Common workflow failures and fixes:**
615+
- **"Dependencies lock file not found"** → Commit pnpm-lock.yaml
616+
- **"Version mismatch"** → Update package.json version to match tag
617+
- **"Repository URL mismatch"** → Ensure repository URL in package.json matches GitHub (case-sensitive)
618+
- **"Cannot publish over previously published version"** → Bump to next patch version using `./scripts/publish-patch.sh`
619+
- **"Resource not accessible by integration" (403)** → Workflow needs `contents: write` permission
620+
- **ESLint errors** → Fix linting issues or temporarily disable linter in workflow
621+
622+
### Quick Fix Script
623+
624+
For common scenarios like needing to republish with fixes, use the helper script:
625+
626+
```bash
627+
./scripts/publish-patch.sh
628+
```
629+
630+
This script handles:
631+
- Version bumping
632+
- Tag management
633+
- Committing and pushing
634+
- Triggering the publish workflow
635+
636+
See `scripts/README.md` for details.
579637

580638
## Support
581639

582640
For questions or issues:
583-
- GitHub Issues: https://github.com/encryptioner/html-to-pdf-generator/issues
641+
- GitHub Issues: https://github.com/Encryptioner/html-to-pdf-generator/issues
584642
- NPM Package: https://www.npmjs.com/package/@encryptioner/html-to-pdf-generator
585-
- GitHub Actions: https://github.com/encryptioner/html-to-pdf-generator/actions
643+
- GitHub Actions: https://github.com/Encryptioner/html-to-pdf-generator/actions

‎.github/workflows/publish.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ jobs:
1919
runs-on: ubuntu-latest
2020

2121
permissions:
22-
contents: read
23-
id-token: write # Required for NPM provenance
22+
contents: write # Required for creating GitHub releases
23+
id-token: write # Required for NPM provenance
2424

2525
steps:
2626
- name: Checkout code

PRODUCTION_READY_SUMMARY.md renamed to docs/PRODUCTION_READY_SUMMARY.md

File renamed without changes.

‎docs/SETUP_SUMMARY.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# NPM Publishing Setup - Complete Summary
2+
3+
## ✅ What's Been Set Up
4+
5+
### 1. GitHub Workflows
6+
7+
#### `.github/workflows/publish.yml`
8+
- Triggers on version tags (v*)
9+
- Runs tests, type checking, and builds
10+
- Publishes to NPM with provenance
11+
- Creates GitHub Releases
12+
- **Fixed issues:**
13+
- Added `contents: write` permission for releases
14+
- Fixed test command: `pnpm test -- run --passWithNoTests`
15+
- Temporarily disabled linter (needs ESLint v9 config)
16+
17+
#### `.github/workflows/ci.yml`
18+
- Runs on pushes to `master`, `pre/**`, `release/**` branches
19+
- Tests across Node.js 18.20.0, 20, and 22
20+
- Same fixes as publish workflow
21+
22+
### 2. Documentation
23+
24+
#### `.github/PUBLISHING.md`
25+
Comprehensive publishing guide covering:
26+
- NPM account setup (no organization needed!)
27+
- Granular access token creation
28+
- Branch strategy (master/pre/release)
29+
- Version tagging workflows
30+
- Troubleshooting common errors
31+
- How to move/retag versions
32+
- Quick reference tables
33+
34+
### 3. Helper Scripts
35+
36+
#### `scripts/publish-patch.sh`
37+
Automated patch version publishing:
38+
```bash
39+
./scripts/publish-patch.sh
40+
```
41+
- Bumps version
42+
- Manages tags
43+
- Pushes to trigger workflow
44+
45+
### 4. Fixed Issues
46+
47+
#### Repository Configuration
48+
- ✅ Added `pnpm-lock.yaml` to git (was ignored)
49+
- ✅ Fixed GitHub URL casing: `encryptioner` → `Encryptioner`
50+
- ✅ Fixed test command syntax
51+
- ✅ Added workflow permissions for releases
52+
53+
#### Build Configuration
54+
- ✅ Tests pass with no test files (`--passWithNoTests`)
55+
- ✅ Linter temporarily disabled (TODO: ESLint v9 config)
56+
- ✅ MCP server builds correctly
57+
58+
## 📋 Required Setup (One-Time)
59+
60+
### Create NPM Granular Access Token
61+
62+
1. Go to https://npmjs.com → Sign in
63+
2. Profile → Access Tokens → Generate New Token → **Granular Access Token**
64+
3. Configure:
65+
- **Name**: `GitHub Actions CI/CD`
66+
- **Expiration**: 90-365 days
67+
- **Permissions**: Read and write
68+
- **Packages**: `@encryptioner/html-to-pdf-generator` or "All packages"
69+
4. Copy the token (starts with `npm_...`)
70+
71+
### Add Token to GitHub Secrets
72+
73+
1. Go to: https://github.com/Encryptioner/html-to-pdf-generator/settings/secrets/actions
74+
2. Click "New repository secret"
75+
3. Name: `NPM_TOKEN`
76+
4. Value: Paste your NPM token
77+
5. Save
78+
79+
**Note:** `GITHUB_TOKEN` is automatic, no setup needed!
80+
81+
## 🚀 How to Publish
82+
83+
### Current Situation
84+
85+
You're on `pre/release/1.0.0` branch with v1.0.0 already published to NPM.
86+
87+
### Recommended: Publish v1.0.1
88+
89+
Run the automated script:
90+
91+
```bash
92+
./scripts/publish-patch.sh
93+
```
94+
95+
Or manually:
96+
97+
```bash
98+
# 1. Bump version
99+
pnpm version patch --no-git-tag-version
100+
101+
# 2. Commit
102+
git add package.json
103+
git commit -m "chore: bump version to 1.0.1"
104+
105+
# 3. Delete old tag
106+
git tag -d v1.0.0
107+
git push origin --delete v1.0.0
108+
109+
# 4. Create new tag
110+
git tag v1.0.1
111+
112+
# 5. Push everything
113+
git push origin pre/release/1.0.0
114+
git push origin v1.0.1
115+
```
116+
117+
### Monitor Progress
118+
119+
1. **GitHub Actions**: https://github.com/Encryptioner/html-to-pdf-generator/actions
120+
2. **NPM Package**: https://www.npmjs.com/package/@encryptioner/html-to-pdf-generator
121+
3. **GitHub Releases**: https://github.com/Encryptioner/html-to-pdf-generator/releases
122+
123+
## 📦 What Gets Published
124+
125+
- Core library (ESM + CJS)
126+
- Node.js adapter (with Puppeteer support)
127+
- React hooks
128+
- Vue composables
129+
- Svelte stores
130+
- MCP server
131+
- TypeScript declarations
132+
- Documentation
133+
134+
## 🔐 Security
135+
136+
- ✅ Safe for public repositories
137+
- ✅ Secrets masked in logs
138+
- ✅ Only maintainers can trigger publish
139+
- ✅ NPM provenance for supply chain security
140+
- ✅ Limited GitHub permissions
141+
142+
## ❓ Troubleshooting
143+
144+
See `.github/PUBLISHING.md` for detailed troubleshooting, including:
145+
- Dependencies lock file errors
146+
- Version mismatches
147+
- Repository URL mismatches
148+
- Cannot republish same version
149+
- GitHub permissions errors
150+
151+
## 📚 Documentation
152+
153+
- **Publishing Guide**: `.github/PUBLISHING.md`
154+
- **Scripts Guide**: `scripts/README.md`
155+
- **Project Guide**: `CLAUDE.md`
156+
- **Package Guide**: `docs/NPM_PACKAGE_GUIDE.md`
157+
158+
## ✨ Next Steps
159+
160+
1. ✅ Setup Complete - Add `NPM_TOKEN` to GitHub Secrets
161+
2. 🚀 Ready to Publish - Run `./scripts/publish-patch.sh`
162+
3. 📊 Monitor - Watch GitHub Actions and NPM
163+
4. 🎉 Done - Package is live!

‎package.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@encryptioner/html-to-pdf-generator",
3-
"version": "1.0.0",
3+
"version": "1.0.1",
44
"description": "Modern multi-page PDF generator from HTML content with smart pagination and styling support",
55
"keywords": [
66
"pdf",
@@ -30,12 +30,12 @@
3030
"license": "MIT",
3131
"repository": {
3232
"type": "git",
33-
"url": "https://github.com/encryptioner/html-to-pdf-generator.git"
33+
"url": "https://github.com/Encryptioner/html-to-pdf-generator.git"
3434
},
3535
"bugs": {
36-
"url": "https://github.com/encryptioner/html-to-pdf-generator/issues"
36+
"url": "https://github.com/Encryptioner/html-to-pdf-generator/issues"
3737
},
38-
"homepage": "https://github.com/encryptioner/html-to-pdf-generator#readme",
38+
"homepage": "https://github.com/Encryptioner/html-to-pdf-generator#readme",
3939
"packageManager": "[email protected]",
4040
"type": "module",
4141
"bin": {

‎scripts/README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Publishing Scripts
2+
3+
Helper scripts for managing package releases.
4+
5+
## publish-patch.sh
6+
7+
Automates the complete patch version release workflow.
8+
9+
**What it does:**
10+
1. Bumps patch version in package.json (e.g., 1.0.0 → 1.0.1)
11+
2. Commits the version bump
12+
3. Deletes old tag if it exists (both local and remote)
13+
4. Creates new version tag
14+
5. Pushes everything to trigger GitHub Actions publish workflow
15+
16+
**Usage:**
17+
```bash
18+
./scripts/publish-patch.sh
19+
```
20+
21+
**When to use:**
22+
- Publishing bug fixes
23+
- After making workflow/configuration changes
24+
- When you need to republish after fixing issues
25+
- Moving a tag to a newer commit
26+
27+
**Prerequisites:**
28+
- All changes committed
29+
- Clean working directory
30+
- On the correct branch (`pre/**` for pre-releases, `master` for production)
31+
32+
**What happens next:**
33+
- GitHub Actions workflow runs automatically
34+
- Package is published to NPM
35+
- GitHub Release is created
36+
37+
**Example output:**
38+
```
39+
===== Publishing Patch Version =====
40+
41+
Current version: 1.0.0
42+
New version will be: 1.0.1
43+
44+
Continue? (y/n) y
45+
46+
Step 1: Updating version to 1.0.1...
47+
Step 2: Committing version bump...
48+
Step 3: Deleting old v1.0.0 tag if it exists...
49+
Step 4: Creating v1.0.1 tag...
50+
Step 5: Getting current branch...
51+
Step 6: Pushing to remote...
52+
53+
✅ Done!
54+
```
55+
56+
## verify-package.cjs
57+
58+
Verifies package structure before publishing.
59+
60+
**Usage:**
61+
```bash
62+
node scripts/verify-package.cjs
63+
```
64+
65+
Checks:
66+
- Package.json exports are valid
67+
- TypeScript declarations exist
68+
- Build outputs are present
69+
- No missing files

0 commit comments

Comments
 (0)