Skip to main content
On this page

Gitorial Authoring - Editing Steps

Editing steps

You can edit any step in isolation while keeping the overall narrative intact. Edits are performed in the Folded view; when ready, generate the Unfolded PR structure from the current Folded timeline.

Step-by-step

  1. Choose the step to edit
    The extension prepares the authoring environment by utilizing git worktrees. Initially only a worktree for the Folded state gets created. On the left side you will find a familiar panel to ‘source control’ called ‘gitorial authoring’. You can pick a step from the timeline by double clicking it. If there are any changes the menu will display them similar to the ‘source control’ panel.

  2. Edit steps
    A user is able to select and edit the files for step N. Each edit modifies the underlying commit sequence that defines the tutorial timeline. Furthermore the user can update the commit message via the UI.

  3. Resolve conflicts (if any)
    If downstream steps depend on content that changed in an earlier step, the authoring interface will guide the user through resolving potential conflicts one by one. See ordering rules like Template must be followed by Solution and Solution must follow Template or Action.

  4. Validate the story
    Once edits are complete, the author can preview the tutorial flow from start to finish. Validation may include running tests, executing build checks, and skimming the diff to ensure each step still teaches the intended concept and logically follows from the previous one. Content rules like Section must change README help keep steps focused.

  5. Create PR-ready structure
    The author explicitly triggers a “Create PR-ready structure” action, which only executes when the timeline is in a valid state. In case of an error the error will be displayed for the user to fix (see Validation). This process expands the Folded state into an Unfolded representation, where each step is written to a corresponding steps/N/ folder.
    The generated structure lives locally and can be inspected before publication.

  6. Open a pull request
    Once satisfied, the author opens a PR for the unfolded state.

Conflicts and cascading changes

Let’s call your change at step x the delta Δx\Delta_x. If a later step modifies the same lines (or depends on the previous behavior), your changes may cause conflicts in steps x+1…nx+1\ldots n. The authoring experience guides you to resolve them in order:

  • Show the earliest impacted step and the exact conflict.
  • Offer suggested resolutions when the intent is clear (e.g., renamed symbol).
  • After resolving, re-run validations, then continue to the next impacted step.

Conflict resolution flow — show: edit step x → detect impact on x+1 → guided resolution → continue

Tips for maintainable steps

  • Teach one idea per step; avoid noisy diffs.
  • Prefer renames over copy/paste; they’re easier to track and resolve.
  • Keep tests green at every step where possible.
  • Use metadata to keep commit messages short, descriptive, and learner-focused.

When you’re done

Once the tutorial reads well and validations pass, move on to opening a pull request to share changes with reviewers.