Skip to content

Commit f3e0ba4

Browse files
pyramationpyramation
committed
bump
1 parent a0f6c30 commit f3e0ba4

File tree

2 files changed

+285
-16
lines changed

2 files changed

+285
-16
lines changed

‎PUBLISH.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
# Publishing Guide
2+
3+
This guide covers the multi-version publishing workflow for the pgsql-parser monorepo, which supports PostgreSQL versions 13-17 with version-specific npm tags.
4+
5+
## Prerequisites
6+
7+
Before publishing any packages, you must build the entire monorepo:
8+
9+
```bash
10+
yarn && yarn build
11+
```
12+
13+
This installs all dependencies and builds all packages in the correct order using Lerna.
14+
15+
## Multi-Version Publishing Overview
16+
17+
The pgsql-parser project uses a sophisticated multi-version publishing system to support different PostgreSQL versions. Each PostgreSQL version has its own:
18+
19+
- **Version numbers** for each package (parser, deparser, types)
20+
- **npm tag** for publishing (pg13, pg14, pg15, pg16, pg17)
21+
- **libpg-query dependency** version
22+
23+
All version mappings are centrally managed in `config/versions.json`:
24+
25+
```json
26+
{
27+
"versions": {
28+
"13": {
29+
"libpg-query": "13.5.7",
30+
"pgsql-parser": "13.18.0",
31+
"pgsql-deparser": "13.17.0",
32+
"@pgsql/types": "13.11.1",
33+
"npmTag": "pg13"
34+
},
35+
"17": {
36+
"libpg-query": "17.5.5",
37+
"pgsql-parser": "17.7.5",
38+
"pgsql-deparser": "17.8.3",
39+
"@pgsql/types": "17.6.1",
40+
"npmTag": "pg17"
41+
}
42+
}
43+
}
44+
```
45+
46+
### 0. Bump the config versions
47+
48+
In the root:
49+
50+
```
51+
yarn bump-versions
52+
```
53+
54+
## Package Publishing Workflows
55+
56+
### 1. Parser Package (`pgsql-parser`)
57+
58+
The parser package uses a version preparation script to generate multiple version-specific packages.
59+
60+
#### Prepare Versions
61+
```bash
62+
cd packages/parser
63+
npm run prepare-versions
64+
```
65+
66+
This script (`scripts/prepare-versions.ts`):
67+
- Reads version configuration from `config/versions.json`
68+
- Creates version-specific directories in `packages/parser/versions/`
69+
- Generates `package.json`, `tsconfig.json`, and source files for each PostgreSQL version
70+
- Each version gets its own libpg-query dependency and npm tag
71+
72+
#### Build and Publish Individual Versions
73+
```bash
74+
# Navigate to a specific version directory
75+
cd packages/parser/versions/17
76+
77+
# Build the package
78+
npm run build
79+
80+
# Publish with the correct tag
81+
npm publish --tag pg17
82+
```
83+
84+
#### Publish All Parser Versions
85+
```bash
86+
cd packages/parser
87+
88+
# Prepare all versions
89+
npm run prepare-versions
90+
91+
# Build and publish each version
92+
for version in versions/*/; do
93+
cd "$version"
94+
npm run build
95+
npm run publish:pkg # Uses the npmTag from config
96+
cd ..
97+
done
98+
```
99+
100+
### 2. Deparser Package (`pgsql-deparser`)
101+
102+
The deparser package uses a template-based approach for multi-version publishing.
103+
104+
#### Prepare Versions
105+
```bash
106+
cd packages/deparser
107+
npm run prepare-versions
108+
```
109+
110+
This runs a complete preparation pipeline:
111+
1. `strip-transformer-types` - Clean up transformer types
112+
2. `strip-direct-transformer-types` - Clean up direct transformer types
113+
3. `strip-deparser-types` - Clean up deparser types
114+
4. `organize-transformers` - Organize transformers by version
115+
5. `generate-version-deparsers` - Generate version-specific deparsers
116+
6. `generate-packages` - Generate package.json files for each version
117+
118+
The `generate-packages` script (`scripts/generate-version-packages.ts`):
119+
- Uses the template from `config/deparser-versions.json`
120+
- Creates version-specific packages in `packages/deparser/versions/`
121+
- Sets up proper dependencies and npm tags for each PostgreSQL version
122+
123+
#### Build and Publish Individual Versions
124+
```bash
125+
# Navigate to a specific version directory
126+
cd packages/deparser/versions/17
127+
128+
# Build the package
129+
npm run build
130+
131+
# Publish with the correct tag
132+
npm publish --tag pg17
133+
```
134+
135+
#### Publish All Deparser Versions
136+
```bash
137+
cd packages/deparser
138+
139+
# Prepare all versions
140+
npm run prepare-versions
141+
142+
# Build and publish each version
143+
for version in versions/*/; do
144+
cd "$version"
145+
npm run build
146+
npm run publish:pkg # Uses the npmTag from config
147+
cd ..
148+
done
149+
```
150+
151+
### 3. Other Packages
152+
153+
For packages without multi-version publishing (utils, traverse, cli, etc.):
154+
155+
```bash
156+
cd packages/{package-name}
157+
npm run build
158+
npm publish
159+
```
160+
161+
## Lerna Publishing
162+
163+
For coordinated publishing across the entire monorepo:
164+
165+
```bash
166+
# Publish all packages that have changed
167+
lerna publish
168+
169+
# Publish with a specific version bump
170+
lerna publish major|minor|patch
171+
172+
# Publish from a specific branch (main only by default)
173+
lerna publish --allow-branch main
174+
```
175+
176+
The Lerna configuration (`lerna.json`) is set up with:
177+
- Independent versioning for each package
178+
- Conventional commits for automatic changelog generation
179+
- Restricted to publishing from the `main` branch
180+
181+
## Complete Publishing Procedure
182+
183+
### For a New Release
184+
185+
1. **Update version configuration** in `config/versions.json` if needed
186+
2. **Build the monorepo**:
187+
```bash
188+
yarn && yarn build
189+
```
190+
191+
3. **Prepare multi-version packages**:
192+
```bash
193+
# Parser versions
194+
cd packages/parser && npm run prepare-versions && cd ../..
195+
196+
# Deparser versions
197+
cd packages/deparser && npm run prepare-versions && cd ../..
198+
```
199+
200+
4. **Publish packages** (choose one approach):
201+
202+
**Option A: Individual package publishing**
203+
```bash
204+
# Publish parser versions
205+
cd packages/parser
206+
for version in versions/*/; do
207+
cd "$version" && npm run build && npm run publish:pkg && cd ..
208+
done
209+
cd ../..
210+
211+
# Publish deparser versions
212+
cd packages/deparser
213+
for version in versions/*/; do
214+
cd "$version" && npm run build && npm run publish:pkg && cd ..
215+
done
216+
cd ../..
217+
218+
# Publish other packages
219+
cd packages/utils && npm run build && npm publish && cd ../..
220+
cd packages/traverse && npm run build && npm publish && cd ../..
221+
# ... repeat for other packages
222+
```
223+
224+
**Option B: Lerna coordinated publishing**
225+
```bash
226+
lerna publish
227+
```
228+
229+
### For Emergency Patches
230+
231+
1. **Create a patch branch** from the target version
232+
2. **Apply fixes** to the relevant packages
233+
3. **Update version numbers** in `config/versions.json`
234+
4. **Follow the complete publishing procedure** above
235+
236+
## Troubleshooting
237+
238+
### Common Issues
239+
240+
**Build failures**: Ensure you've run `yarn && yarn build` in the root directory first.
241+
242+
**Version conflicts**: Check that `config/versions.json` has consistent version numbers across all packages.
243+
244+
**npm tag issues**: Verify that the npmTag in the configuration matches what you're publishing with.
245+
246+
**Permission errors**: Ensure you're logged into npm with an account that has publish permissions for the `@pgsql` scope and `pgsql-*` packages.
247+
248+
### Verification
249+
250+
After publishing, verify the packages are available:
251+
252+
```bash
253+
# Check latest versions
254+
npm view pgsql-parser dist-tags
255+
npm view pgsql-deparser dist-tags
256+
257+
# Check specific version tags
258+
npm view pgsql-parser@pg17
259+
npm view pgsql-deparser@pg17
260+
```
261+
262+
## Package Dependencies
263+
264+
The multi-version system maintains these relationships:
265+
- `pgsql-parser` depends on `libpg-query`, `pgsql-deparser`, and `@pgsql/types`
266+
- `pgsql-deparser` depends only on `@pgsql/types`
267+
- All versions must be compatible within the same PostgreSQL version
268+
269+
When updating versions, ensure all related packages are updated together to maintain compatibility.

‎config/versions.json‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,39 @@
11
{
22
"versions": {
33
"13": {
4-
"libpg-query": "13.5.7",
5-
"pgsql-parser": "13.18.0",
6-
"pgsql-deparser": "13.17.0",
4+
"libpg-query": "13.6.0",
5+
"pgsql-parser": "13.19.0",
6+
"pgsql-deparser": "13.18.0",
77
"@pgsql/types": "13.11.1",
88
"npmTag": "pg13"
99
},
1010
"14": {
11-
"libpg-query": "14.2.5",
12-
"pgsql-parser": "14.0.1",
13-
"pgsql-deparser": "14.0.1",
11+
"libpg-query": "14.3.0",
12+
"pgsql-parser": "14.1.0",
13+
"pgsql-deparser": "14.1.0",
1414
"@pgsql/types": "14.1.1",
1515
"npmTag": "pg14"
1616
},
1717
"15": {
18-
"libpg-query": "15.4.8",
19-
"pgsql-parser": "15.0.0",
20-
"pgsql-deparser": "15.0.0",
18+
"libpg-query": "15.5.0",
19+
"pgsql-parser": "15.1.0",
20+
"pgsql-deparser": "15.1.0",
2121
"@pgsql/types": "15.1.1",
2222
"npmTag": "pg15"
2323
},
2424
"16": {
25-
"libpg-query": "16.5.5",
26-
"pgsql-parser": "16.0.0",
27-
"pgsql-deparser": "16.0.0",
25+
"libpg-query": "16.6.0",
26+
"pgsql-parser": "16.1.0",
27+
"pgsql-deparser": "16.1.0",
2828
"@pgsql/types": "16.1.1",
2929
"npmTag": "pg16"
3030
},
3131
"17": {
32-
"libpg-query": "17.5.5",
33-
"pgsql-parser": "17.7.5",
34-
"pgsql-deparser": "17.8.3",
32+
"libpg-query": "17.6.0",
33+
"pgsql-parser": "17.7.6",
34+
"pgsql-deparser": "17.8.4",
3535
"@pgsql/types": "17.6.1",
3636
"npmTag": "pg17"
3737
}
3838
}
39-
}
39+
}

0 commit comments

Comments
 (0)