Skip to content

Commit fba361b

Browse files
zhjwpkuzhjwpku
committed
feat: set up the book structure
1 parent 86b45c6 commit fba361b

16 files changed

Lines changed: 1614 additions & 0 deletions

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Downloaded thread data and generated content
2+
data/
3+
4+
# Generated mdBook output
5+
book
6+
7+
# Personal prompt file (copy from QUICK_PROMPT.template)
8+
QUICK_PROMPT.txt

‎BLOG_GENERATION_PROMPT.md‎

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
# PostgreSQL Weekly Blog Generation Prompt Template
2+
3+
## Basic Prompt Template
4+
5+
Use this template for each thread you want to convert into a blog post. Simply replace `{THREAD_ID_OR_URL}` with your actual thread ID or URL.
6+
7+
---
8+
9+
### Prompt:
10+
11+
```
12+
I need you to act as a PostgreSQL expert and technical writer to generate a high-quality blog post from a PostgreSQL mailing list thread.
13+
14+
**Thread ID/URL:** {THREAD_ID_OR_URL}
15+
16+
**Instructions:**
17+
18+
1. **Fetch the thread data:**
19+
- Run: `python3 tools/fetch_data.py --thread-id "{THREAD_ID_OR_URL}"`
20+
- This will download the HTML, convert to Markdown, and save attachments
21+
22+
2. **Analyze the content:**
23+
- Read the converted Markdown file in `data/threads/YYYY-MM-DD/<thread-id>/thread.md`
24+
- Review the original HTML if you need more context
25+
- Check the `attachments/` folder for any patch files
26+
- If there are multiple patch versions (v1, v2, v3, etc.), use `diff` to understand what changed between versions
27+
28+
3. **Generate a technical blog post with:**
29+
- **Clear title:** Based on the main topic discussed
30+
- **Introduction:** Brief context and why this matters
31+
- **Technical Analysis:**
32+
- Key discussion points and decisions
33+
- Code examples or patch highlights (if relevant)
34+
- Evolution of the solution (compare patch versions if multiple exist)
35+
- **Community Insights:**
36+
- Important reviewer feedback
37+
- Issues discovered and how they were resolved
38+
- **Technical Details:**
39+
- Implementation approaches
40+
- Edge cases discussed
41+
- Performance considerations (if any)
42+
- **Current Status:** Where the patch/discussion stands
43+
- **Conclusion:** Summary and implications for PostgreSQL users
44+
45+
4. **Write TWO versions (English and Chinese):**
46+
- **English version:** Professional technical writing style, clear explanations
47+
- **Chinese version:** Professional Chinese technical writing, natural terminology
48+
- **Both versions:** Code blocks with proper syntax highlighting, links to documentation
49+
50+
5. **Save the blogs:**
51+
- Determine the appropriate year and week number based on the thread date or current date
52+
- Generate a descriptive filename based on the content
53+
- **Create directories if needed and save TWO files:**
54+
- `src/en/{year}/{week}/{filename}.md` - English version
55+
- `src/cn/{year}/{week}/{filename}.md` - Chinese version
56+
- Update `src/SUMMARY.md` to include BOTH blog entries in their respective language sections
57+
- Update both language week README files if they don't exist
58+
59+
**Additional Context:**
60+
- You have full access to all downloaded files in the thread directory
61+
- Use your PostgreSQL expertise to provide valuable insights
62+
- Focus on technical accuracy and clarity
63+
- Highlight what developers and DBAs should know about this discussion
64+
- **Year/Week determination:** Check the thread's date in metadata.txt or use the current date to determine the appropriate year and ISO week number for organizing the blog
65+
66+
Please start by fetching the data and then generate the blog post.
67+
```
68+
69+
---
70+
71+
## Advanced Prompt Template (With Specific Requirements)
72+
73+
Use this version when you want more control over the output:
74+
75+
```
76+
Act as a PostgreSQL core developer and technical writer. Generate a comprehensive blog post from the following mailing list thread.
77+
78+
**Thread:** {THREAD_ID_OR_URL}
79+
80+
**Step 1: Data Collection**
81+
Run: `python3 tools/fetch_data.py --thread-id "{THREAD_ID_OR_URL}"`
82+
83+
**Step 2: Content Analysis**
84+
Review:
85+
- Markdown content: `data/threads/*/thread.md`
86+
- Patches in: `data/threads/*/attachments/`
87+
- For multiple patch versions, run: `diff -u v1-*.patch v2-*.patch` to see evolution
88+
89+
**Step 3: Blog Structure**
90+
91+
Create a blog with these sections:
92+
93+
### Title
94+
[Generate a concise, descriptive title]
95+
96+
### Metadata
97+
- Date: [Today's date]
98+
- Category: PostgreSQL Development
99+
- Tags: [Extract relevant tags from content]
100+
101+
### Introduction (2-3 paragraphs)
102+
- What problem does this address?
103+
- Why is this discussion important?
104+
- Who should care about this?
105+
106+
### Background
107+
- Current limitations or issues
108+
- Motivation for the proposed change
109+
110+
### Technical Deep Dive
111+
- **Proposed Solution:** Explain the approach
112+
- **Implementation Details:** Key technical points
113+
- **Code Walkthrough:** Highlight important code sections from patches
114+
- **Evolution:** If multiple patch versions exist, show how the solution evolved
115+
- Compare patches using diff
116+
- Explain what changed and why
117+
118+
### Community Discussion
119+
- Key reviewer comments
120+
- Issues/bugs discovered
121+
- Suggested improvements
122+
- Debates or alternative approaches
123+
124+
### Technical Considerations
125+
- Performance implications
126+
- Backward compatibility
127+
- Security considerations
128+
- Edge cases and how they're handled
129+
130+
### Patch Evolution (if applicable)
131+
For each major version:
132+
- v1: [Initial approach]
133+
- v2: [What changed - use actual diff output]
134+
- v3: [Further refinements]
135+
136+
### Current Status
137+
- Review status
138+
- Remaining concerns
139+
- Expected timeline (if mentioned)
140+
141+
### Impact & Use Cases
142+
- Who will benefit?
143+
- Example use cases
144+
- Migration considerations
145+
146+
### Conclusion
147+
- Summary of key points
148+
- Broader implications
149+
- What to watch for
150+
151+
### References
152+
- Link to mailing list thread
153+
- Related documentation
154+
- Previous related discussions (if mentioned)
155+
156+
**Step 4: File Management**
157+
- Determine year and week: [Calculate from thread date or today's date]
158+
- Create paths: `src/en/{year}/{week}/` and `src/cn/{year}/{week}/`
159+
- Filename: [Generate from main topic, lowercase-with-hyphens]
160+
- Save English version to `src/en/{year}/{week}/{filename}.md`
161+
- Save Chinese version to `src/cn/{year}/{week}/{filename}.md`
162+
- Update `src/SUMMARY.md` in both language sections
163+
164+
**Writing Guidelines:**
165+
- Use clear, technical language
166+
- Include code blocks with syntax highlighting
167+
- Add inline comments for complex code
168+
- Use bullet points for clarity
169+
- Bold important terms on first use
170+
- Length: 1500-2500 words
171+
- Tone: Professional, educational, engaging
172+
173+
**Quality Checks:**
174+
- [ ] All technical terms correctly explained
175+
- [ ] Code examples are accurate
176+
- [ ] Patch comparisons are clear
177+
- [ ] Links are functional
178+
- [ ] SUMMARY.md is updated
179+
- [ ] File is in correct directory
180+
181+
Begin the analysis and blog generation now.
182+
```
183+
184+
---
185+
186+
## Quick Prompt (Minimal Version)
187+
188+
For faster processing:
189+
190+
```
191+
Generate a PostgreSQL technical blog from this thread: {THREAD_ID_OR_URL}
192+
193+
1. Fetch: `python3 tools/fetch_data.py --thread-id "{THREAD_ID_OR_URL}"`
194+
2. Read the Markdown content and patches
195+
3. Compare patch versions if multiple exist (use diff)
196+
4. Write a technical blog covering:
197+
- What problem is being solved
198+
- How the solution works
199+
- Key discussion points
200+
- Patch evolution (if applicable)
201+
- Current status
202+
5. Save to: `src/{year}/{appropriate-week}/{descriptive-name}.md`
203+
6. Update `src/SUMMARY.md`
204+
205+
Write as a PostgreSQL expert. Focus on technical accuracy and clarity.
206+
```
207+
208+
---
209+
210+
## Example Usage
211+
212+
### Example 1: Simple usage
213+
```
214+
I need you to act as a PostgreSQL expert and technical writer to generate a high-quality blog post from a PostgreSQL mailing list thread.
215+
216+
**Thread ID/URL:** https://www.postgresql.org/message-id/flat/CACJufxGn+bMNPyrMTe0-W4fLmkFVXSr-6cvFos9mGsp-5u-RXw@mail.gmail.com
217+
218+
[... rest of basic prompt ...]
219+
```
220+
221+
### Example 2: Just the thread ID
222+
```
223+
Generate a PostgreSQL technical blog from this thread: CACJufxGn+bMNPyrMTe0-W4fLmkFVXSr-6cvFos9mGsp-5u-RXw@mail.gmail.com
224+
225+
[... rest of quick prompt ...]
226+
```
227+
228+
---
229+
230+
## Tips for Best Results
231+
232+
1. **Let the Agent Decide:** Don't micromanage the filename or exact structure
233+
2. **Provide Context:** If you know the thread is about a specific feature, mention it
234+
3. **Review Output:** Always review the generated blog for technical accuracy
235+
4. **Iterate:** Ask for improvements: "Make the technical section more detailed" or "Add more code examples"
236+
237+
---
238+
239+
## Multi-Thread Batch Processing Prompt
240+
241+
For processing multiple threads at once:
242+
243+
```
244+
I have {N} PostgreSQL mailing list threads to convert into blog posts. Process them one by one:
245+
246+
**Threads:**
247+
1. {THREAD_ID_1}
248+
2. {THREAD_ID_2}
249+
3. {THREAD_ID_3}
250+
251+
For each thread:
252+
1. Fetch data: `python3 tools/fetch_data.py --thread-id "{THREAD_ID}"`
253+
2. Generate TWO versions of the technical blog post (English and Chinese)
254+
3. Save to appropriate year/week directories:
255+
- English: `src/en/{year}/{week}/{filename}.md`
256+
- Chinese: `src/cn/{year}/{week}/{filename}.md`
257+
4. Update `src/SUMMARY.md` in both language sections
258+
259+
After all are done, provide a summary of:
260+
- Blogs created
261+
- File locations
262+
- Any issues encountered
263+
264+
Use the same PostgreSQL expert approach for all blogs.
265+
```
266+
267+
---
268+
269+
## Customization Variables
270+
271+
You can customize these aspects in your prompt:
272+
273+
- `{THREAD_ID_OR_URL}` - Required: The thread to process
274+
- `{SPECIFIC_FOCUS}` - Optional: "Focus on performance implications"
275+
- `{TARGET_AUDIENCE}` - Optional: "Write for DBAs" or "Write for developers"
276+
- `{BLOG_LENGTH}` - Optional: "Keep it under 1000 words" or "Comprehensive analysis"
277+
- `{TONE}` - Optional: "Conversational" or "Academic"
278+
- `{WEEK_NUMBER}` - Optional: Specify the week if you know it
279+
280+
---
281+
282+
## Common Follow-up Prompts
283+
284+
After initial generation:
285+
286+
- "Make the technical section more detailed with code examples"
287+
- "Add a comparison table for the different patch versions"
288+
- "Simplify the explanation for junior developers"
289+
- "Add more context about why this feature is important"
290+
- "Compare this approach with how other databases solve this"
291+
- "Add a 'Try it yourself' section with examples"

‎QUICK_PROMPT.template‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
I need you to act as a PostgreSQL expert and technical writer to generate a high-quality blog post from a PostgreSQL mailing list thread.
2+
3+
**Instructions:**
4+
5+
1. **Fetch the thread data:**
6+
- Run: `python3 tools/fetch_data.py --thread-id "PASTE_YOUR_THREAD_ID_HERE"`
7+
- This will download the HTML, convert to Markdown, and save attachments
8+
9+
2. **Analyze the content:**
10+
- Read the converted Markdown file in `data/threads/YYYY-MM-DD/<thread-id>/thread.md`
11+
- Review the original HTML if you need more context
12+
- Check the `attachments/` folder for any patch files
13+
- If there are multiple patch versions (v1, v2, v3, etc.), use `diff` to understand what changed between versions
14+
15+
3. **Generate TWO versions of the technical blog post (English and Chinese):**
16+
17+
**Both versions should include:**
18+
- **Clear title:** Based on the main topic discussed
19+
- **Introduction:** Brief context and why this matters
20+
- **Technical Analysis:**
21+
- Key discussion points and decisions
22+
- Code examples or patch highlights (if relevant)
23+
- Evolution of the solution (compare patch versions if multiple exist)
24+
- **Community Insights:**
25+
- Important reviewer feedback
26+
- Issues discovered and how they were resolved
27+
- **Technical Details:**
28+
- Implementation approaches
29+
- Edge cases discussed
30+
- Performance considerations (if any)
31+
- **Current Status:** Where the patch/discussion stands
32+
- **Conclusion:** Summary and implications for PostgreSQL users
33+
34+
4. **Writing guidelines:**
35+
- **English version:** Professional technical writing style, clear explanations for complex concepts
36+
- **Chinese version (中文版本):**
37+
- Professional technical writing in Chinese
38+
- Maintain technical accuracy with proper terminology
39+
- Use 中文 for explanations but keep code/SQL examples in original form
40+
- Natural Chinese technical writing style (不要直译，要符合中文技术文章习惯)
41+
- **Both versions:**
42+
- Code blocks with proper syntax highlighting
43+
- Links to relevant documentation or references
44+
45+
5. **Save the blogs:**
46+
- Determine the appropriate year and week number based on the thread date or current date
47+
- Generate a descriptive filename based on the content (e.g., `pg-get-role-ddl-functions`)
48+
- **Create directories if needed and save TWO files:**
49+
- `src/en/{year}/{week}/{filename}.md` - English version
50+
- `src/cn/{year}/{week}/{filename}.md` - Chinese version (中文版本)
51+
- Update `src/SUMMARY.md` to include BOTH blog entries in their respective language sections
52+
- Update both language week README files if they don't exist:
53+
- `src/en/{year}/{week}/README.md`
54+
- `src/cn/{year}/{week}/README.md`
55+
56+
- **Example SUMMARY.md format:**
57+
```markdown
58+
# 🇬🇧 English
59+
- [2026](./en/2026/README.md)
60+
- [Week 03](./en/2026/03/README.md)
61+
- [Topic Name](./en/2026/03/topic-name.md)
62+
63+
# 🇨🇳 中文
64+
- [2026](./cn/2026/README.md)
65+
- [第 03 周](./cn/2026/03/README.md)
66+
- [主题名称](./cn/2026/03/topic-name.md)
67+
```
68+
69+
**Additional Context:**
70+
- You have full access to all downloaded files in the thread directory
71+
- Use your PostgreSQL expertise to provide valuable insights
72+
- Focus on technical accuracy and clarity
73+
- Highlight what developers and DBAs should know about this discussion
74+
- **Year/Week determination:** Check the thread's date in metadata.txt or use the current date to determine the appropriate year and ISO week number for organizing the blog
75+
76+
Please start by fetching the data and then generate the blog post.

0 commit comments

Comments
 (0)