Skip to content

Commit 94ab476

Browse files
crheckmancrheckman
committed
Fix production deployment to properly remove deleted audits
Changes: - Use rsync --delete in deploy.yml to properly sync files - Update INSTRUCTOR_GUIDE.md with new GitHub Pages workflow - Document process for promoting audits from staging/ to production This ensures deleted files (like multimodality_audit.mdx) are properly removed from production, and provides clear instructions for moving approved audits from staging/ to root directory for publication.
1 parent 6a3c02b commit 94ab476

File tree

2 files changed

+209
-96
lines changed

2 files changed

+209
-96
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,5 +18,5 @@ jobs:
1818
cd ~/vla-build
1919
git pull origin main
2020
npm run build
21-
cp -r out/* /var/www/vlm-robotics.dev/public_html/
21+
rsync -av --delete out/ /var/www/vlm-robotics.dev/public_html/
2222
echo "Deployment completed at $(date)"

‎INSTRUCTOR_GUIDE.md‎

Lines changed: 208 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,246 @@
1-
# Instructor Guide: Paper Audit Review System
1+
# Instructor Guide: Paper Audit Review Workflow
22

3-
## Quick Start
3+
## Overview
44

5-
### Setting Up for Review
5+
Students submit paper audits via Pull Requests to the `staging` branch. The system automatically:
6+
1. Runs a standards linter
7+
2. Deploys preview to GitHub Pages
8+
3. Posts preview link in PR comments
69

7-
1. **Student submits PR to staging:**
8-
- Student creates PR from their branch → `staging`
9-
- PR includes their audit file in `content/textbook/audits/`
10+
Once approved, you promote the audit from `staging/` to production and merge to `main`.
1011

11-
2. **Merge to staging for review:**
12-
```bash
13-
gh pr merge 23 --merge --repo arpg/vla-foundations --into staging
14-
```
15-
- This triggers automatic deployment to `vlm-robotics.dev/staging/`
16-
- Wait ~2-3 minutes for deployment to complete
12+
---
1713

18-
3. **Access review interface:**
19-
- Navigate to: `vlm-robotics.dev/staging/textbook/audits/{slug}?review=true`
20-
- For PR 23 (multimodality audit): `vlm-robotics.dev/staging/textbook/audits/multimodality_audit?review=true`
14+
## Student Submission Workflow
2115

22-
### Reviewing and Commenting
16+
### 1. Student Creates PR
2317

24-
1. **Add comments:**
25-
- Click the comment button (bottom right)
26-
- Select the section you're commenting on
27-
- Write your feedback
28-
- Click "Add Comment"
29-
- Comments automatically save to `database/comments/{pr-number}.json`
18+
Students follow these steps (from `content/course/assignments/paper-audit.mdx`):
3019

31-
2. **Mark comments as resolved:**
32-
- As students address feedback, click "Mark Resolved"
33-
- Resolved comments turn green
20+
```bash
21+
git checkout -b audit/username-topic
22+
# Add audit file to: content/textbook/audits/staging/username.mdx
23+
git add content/textbook/audits/staging/username.mdx
24+
git commit -m "audit: add [Paper] deep-dive by [Name]"
25+
git push origin audit/username-topic
26+
```
27+
28+
Then create PR with:
29+
- **Base branch:** `staging`
30+
- **Title:** `Audit: [Paper Topic] - [Name]`
31+
32+
### 2. Automated Linter Check
33+
34+
The `vla-audit.yml` workflow automatically runs:
35+
36+
**Standards Checked:**
37+
- ✅ Semantic line breaks (one sentence per line)
38+
- ✅ Clean git history (no "Merge branch" commits)
39+
40+
**If linter fails:**
41+
- Bot posts detailed instructions in PR comments
42+
- Build is blocked until standards are met
3443

35-
3. **View all comments:**
36-
- Comment sidebar shows all feedback for the PR
37-
- Filter by resolved/unresolved status
44+
**If linter passes:**
45+
- Build deploys to: `https://arpg.github.io/vla-foundations/staging/pulls/{PR_NUMBER}/textbook/audits/staging/{username}/`
46+
- Bot posts preview link in PR comments
3847

39-
### Finalizing the Review
48+
### 3. Instructor Review
4049

41-
1. **When satisfied with revisions:**
42-
```bash
43-
git checkout staging
44-
git pull origin staging
50+
Navigate to the preview URL (posted in PR comments) to review the rendered audit.
4551

46-
# Merge staging → main to publish
47-
git checkout main
48-
git merge staging
49-
git push origin main
50-
```
52+
**Add feedback directly in GitHub PR:**
53+
- Use GitHub's native PR review features
54+
- Comment on specific lines
55+
- Request changes or approve
56+
57+
**Common feedback areas:**
58+
- Mathematical rigor and LaTeX correctness
59+
- Architectural depth and comparative analysis
60+
- Citations and references
61+
- Physical grounding critique (the "load-bearing" analysis)
62+
63+
---
64+
65+
## Promoting Audit to Production (Merge-Ready)
66+
67+
When an audit reaches "Level 3 (A - Mastery)" quality:
68+
69+
### Step 1: Move File from Staging to Production
70+
71+
```bash
72+
# Checkout the PR branch
73+
gh pr checkout {PR_NUMBER}
5174

52-
2. **Published audit appears at:**
53-
- Production: `vlm-robotics.dev/textbook/audits/{slug}`
54-
- Comments persist but review UI hidden in production
75+
# Move the audit file to production location
76+
git mv content/textbook/audits/staging/{username}.mdx content/textbook/audits/{canonical-name}.mdx
5577

56-
## Workflow Diagram
78+
# Example:
79+
git mv content/textbook/audits/staging/gyanigkali.mdx content/textbook/audits/multimodality_audit.mdx
5780

81+
# Commit the promotion
82+
git commit -m "Promote audit to production: ready for merge"
83+
84+
# Push the change
85+
git push
5886
```
59-
Student Branch → PR to Staging → Instructor Reviews → Revisions → Merge to Main
60-
↓ ↓ ↓
61-
Auto-deploy to Add comments Push updates
62-
/staging/ via web UI to same PR
87+
88+
### Step 2: Merge PR to Staging
89+
90+
```bash
91+
gh pr merge {PR_NUMBER} --merge --repo arpg/vla-foundations
6392
```
6493

94+
This merges the PR into `staging` branch.
95+
96+
### Step 3: Merge Staging to Main
97+
98+
```bash
99+
git checkout main
100+
git pull origin main
101+
git merge staging
102+
git push origin main
103+
```
104+
105+
### Step 4: Verify Production Deployment
106+
107+
The `Deploy to Production` workflow will automatically run and:
108+
- Pull latest `main` branch
109+
- Run `npm run build`
110+
- Sync to production server with `rsync --delete`
111+
- Deploy to: `https://vlm-robotics.dev/textbook/audits/{canonical-name}/`
112+
113+
Check the deployment: https://github.com/arpg/vla-foundations/actions/workflows/deploy.yml
114+
115+
---
116+
65117
## URL Structure
66118

67-
- **Staging (review mode):** `vlm-robotics.dev/staging/textbook/audits/{slug}?review=true`
68-
- **Staging (public view):** `vlm-robotics.dev/staging/textbook/audits/{slug}`
69-
- **Production:** `vlm-robotics.dev/textbook/audits/{slug}`
70-
- **Audits index:** `vlm-robotics.dev/textbook/audits/`
119+
| Environment | Location | Audience |
120+
|------------|----------|----------|
121+
| **PR Preview** | `arpg.github.io/vla-foundations/staging/pulls/{PR}/...` | Student + Instructor |
122+
| **Staging** | `vlm-robotics.dev/staging/...` | Testing only |
123+
| **Production** | `vlm-robotics.dev/textbook/audits/{canonical-name}` | Public |
71124

72-
## Comment Persistence
125+
---
73126

74-
- Comments stored in: `database/comments/{pr-number}.json`
75-
- Committed to git repository
76-
- Survive force pushes and rebases (tied to PR number)
77-
- Can be exported for grading records
127+
## File Structure
78128

79-
## Tips
129+
```
130+
content/textbook/audits/
131+
├── staging/ # Student drafts under review
132+
│ ├── gyanigkali.mdx # PR #23 - in review
133+
│ ├── johndoe.mdx # PR #24 - in review
134+
│ └── .gitkeep
135+
├── multimodality_audit.mdx # Published audit (merged from staging/)
136+
├── siglip_audit.mdx # Published audit
137+
└── _template.mdx # Template for students
138+
```
80139

81-
1. **Section Organization:**
82-
- Use consistent section names across audits
83-
- Common sections: Introduction, Architecture, Evaluation, Conclusion
140+
**Important:** Files in `staging/` are **only visible in preview deployments**, not in production. Once approved, they **must be moved** to the root `audits/` directory to appear at `vlm-robotics.dev`.
84141

85-
2. **Effective Feedback:**
86-
- Be specific about what needs improvement
87-
- Reference line numbers or specific claims
88-
- Suggest resources or examples
89-
- Mark minor comments vs. critical issues
142+
---
90143

91-
3. **Student Updates:**
92-
- Students push to same branch
93-
- Re-merge to staging to see updates
94-
- Previous comments remain, check if addressed
144+
## Grading Levels
95145

96-
4. **Multiple Reviewers:**
97-
- All comments stored centrally
98-
- Add author names to comments for multi-instructor courses
146+
### Level 1 (C): Basic Summary
147+
- Correct frontmatter and basic formatting
148+
- Summary of paper's main contributions
149+
- Basic LaTeX rendering
99150

100-
## Troubleshooting
151+
### Level 2 (B): Technical Deep-Dive
152+
- High technical depth with architectural details
153+
- Correct mathematical formulations
154+
- Sound critique of the model
155+
- Proper citations
101156

102-
**Deployment not updating:**
103-
- Check GitHub Actions: `https://github.com/arpg/vla-foundations/actions`
104-
- SSH to server and check logs: `~/vla-staging/`
157+
### Level 3 (A - Mastery): Merge-Ready
158+
- Exhaustive technical analysis
159+
- Comparative deep-dive across multiple papers
160+
- Original insights on scaling laws and bottlenecks
161+
- Physical grounding critique (semantic-motor gap, information decay)
162+
- Professional "Senior Staff" engineering quality
163+
- **Ready to merge to main as canonical reference**
105164

106-
**Comments not saving:**
107-
- Check API endpoint: `/api/comments/{prNumber}`
108-
- Verify `database/comments/` directory exists and is writable
165+
---
109166

110-
**Audit not appearing:**
111-
- Verify MDX file exists in `content/textbook/audits/`
112-
- Check frontmatter includes required fields: `title`, `prNumber`
113-
- Ensure file ends in `.mdx`
167+
## Troubleshooting
114168

115-
## Advanced Features
169+
### Linter Keeps Failing
116170

117-
### Bulk Comment Export
171+
**Check line breaks:**
118172
```bash
119-
# Export all comments for grading
120-
cat database/comments/23.json | jq '.comments'
173+
# The student's file should have semantic line breaks
174+
# Bad:
175+
Multi-modality is the framework that enables a model to process and generate information across disparate data types. In robotics, this represents the shift from a robot that sees its environment versus one that can understand it.
176+
177+
# Good:
178+
Multi-modality is the framework that enables a model to process and generate information across disparate data types.
179+
In robotics, this represents the shift from a robot that sees its environment versus one that can understand it.
121180
```
122181

123-
### Custom Sections
124-
Update `CommentSidebar.tsx` to add new section options:
125-
```tsx
126-
<option value="your-section">Your Section</option>
182+
**Check git history:**
183+
```bash
184+
# If student has merge commits:
185+
git log --oneline
186+
# Should not see: "Merge branch 'main'" or "Merge branch 'staging'"
187+
188+
# Student needs to rebase:
189+
git rebase staging
190+
git push --force-with-lease
191+
```
192+
193+
### Preview Isn't Deploying
194+
195+
1. Check GitHub Actions: https://github.com/arpg/vla-foundations/actions
196+
2. Verify linter passed (green checkmark)
197+
3. Check PR comments for deployment link
198+
199+
### Production Page Still Shows Old Audit
200+
201+
This happens if the deploy script doesn't delete old files.
202+
203+
**Fix:** The deploy.yml now uses `rsync --delete` to properly sync files. Force a redeploy:
204+
```bash
205+
git commit --allow-empty -m "Trigger redeploy"
206+
git push origin main
127207
```
128208

129-
### Authentication (Future)
130-
Currently no auth required. To add:
131-
- Implement simple password check
132-
- Or integrate GitHub OAuth
133-
- See TODO in `app/api/comments/[prNumber]/route.ts`
209+
### Student Can't Find Their Preview
210+
211+
The preview URL is posted automatically in PR comments by the bot:
212+
- Look for the comment from `github-actions` bot
213+
- URL format: `https://arpg.github.io/vla-foundations/staging/pulls/{PR}/textbook/audits/staging/{username}/`
214+
215+
---
216+
217+
## Tips for Effective Reviews
218+
219+
1. **Use GitHub's PR review features** - Line-specific comments are best
220+
2. **Require semantic line breaks** - Makes commenting much easier
221+
3. **Check LaTeX rendering** - View the preview, not just the markdown
222+
4. **Verify references** - Click through to cited papers
223+
5. **Test on mobile** - Ensure equations and diagrams are responsive
224+
6. **Look for the "load-bearing" analysis** - This is what distinguishes A-level work
225+
226+
---
227+
228+
## Quick Reference Commands
229+
230+
```bash
231+
# Review a PR
232+
gh pr checkout {PR_NUMBER}
233+
gh pr view {PR_NUMBER} --web
234+
235+
# Check linter locally
236+
python3 scripts/audit_linter.py
237+
238+
# Promote to production
239+
git mv content/textbook/audits/staging/{user}.mdx content/textbook/audits/{name}.mdx
240+
git commit -m "Promote audit to production"
241+
git push
242+
243+
# Merge to staging and main
244+
gh pr merge {PR_NUMBER} --merge
245+
git checkout main && git merge staging && git push origin main
246+
```

0 commit comments

Comments
 (0)