Gitorial Authoring - Pull Requests

Pull Requests

Pull requests encapsulate your authoring changes and present them in a way that matches how readers experience the tutorial: step by step.

Author flow

1. Review your Folded changes and ensure they are coherent step-by-step.
2. Trigger “Create PR-ready structure” to materialize Unfolded step-N/ folders.
3. From the authoring UI, choose “Open PR”.
4. The PR is generated with step-aware context:
   • A summary of which steps changed (e.g., steps 7 and 12)
   • Per-step diffs that show exactly what learners will see change, with links to relevant validation rules (e.g., README must be last)
   • Links to open the Unfolded step-N/ view for quick local repro

Reviewer flow

On GitHub (or your forge of choice), reviewers can see:

• A high-level summary of impacted steps
• Per-step review checklists (e.g., Does the step teach one idea? Are tests green?)
• Conventional Git diffs, with links back to the Unfolded folders for context

Even if $\Delta_x$ causes subsequent adjustments at $x+k$, only steps that truly changed content are highlighted as primary; downstream mechanical conflict resolutions are labeled accordingly.

Branching strategy

• Feature branches per tutorial (or per large refactor)
• One PR per coherent authoring change (ideally touching a small set of steps)
• Keep the main branch always releasable

CI suggestions

• Validate that Unfolded is rebuilt correctly from the current Folded timeline
• Run tests/linters for each changed step
• Generate a preview site or step-by-step viewer artifacts

Importing PRs back into authoring

If review suggestions are made directly on GitHub, you can pull the branch locally, import changes to the Unfolded worktree, rebuild the Folded timeline, and continue authoring. The mapping is the same, just applied in reverse: Unfolded ⇄ Folded.