Skip to content

History and versions

Every published SpecsGraph revision is a Git commit. Browse a node's history, compare two versions, roll back through a proposal and read changes with git log.

Every revision is a commit

When a proposal is approved, SpecsGraph commits the change to the proposal's branch under spec/ and opens a pull request to the base branch, which follows your repository's usual merge rules. When that pull request is merged, the proposal is Published and the commit becomes a revision: the graph shows it as current.

Each revision records:

  • the proposal it came from, with its title, diff and review threads
  • the author: a person, or an agent together with the person whose token it used
  • the person who approved it
  • when it was published, and the commit and pull request it produced

History only grows. A later change adds a revision on top, and a rollback is one more revision. A withdrawn proposal never becomes a revision, but it stays readable with its threads, so you can still find an idea that was tried and dropped.

The History tab

The History tab sits next to Map and Requirements above the canvas. It lists the revisions that changed the nodes in scope at your zoom level: the whole project at system level, one context, one service or a single requirement. The system graph explains the zoom levels.

Zoom in on ORD-13 "Release reservations after 15 minutes idle" and its history reads like this:

CommitWhat changedProposal
e40f6a8Idle timeout restored to 15 minutesRestore the 15-minute reservation window
5be7d13Idle timeout shortened to 5 minutesShorter reservations during sales
a1c9e02Created with an idle timeout of 15 minutesCheckout reserves stock before payment

Select a revision to see its diff, who wrote and approved it, and the threads from its review.

Compare two versions

Select any two revisions in the History tab and choose Compare. SpecsGraph shows every node that changed between them, before and after, in the same layout as a proposal diff. Changes across several revisions are combined, so you see where the spec ended up rather than each step on the way.

Compare an old revision with the current one to answer practical questions: what changed in the Orders context since the last release, or which rules a new team member should know have moved since the onboarding notes were written.

Roll back a change

Rolling back never deletes history. You restore an earlier version by opening a proposal, and that proposal is reviewed like any other. Northwind did this when a 5-minute timeout on ORD-13 led to too many abandoned checkouts.

  1. Find the version you want

    Open the History tab for ORD-13 and select revision a1c9e02, the last one with the 15-minute timeout.

  2. Choose Restore this version

    SpecsGraph opens a proposal that sets the node back to that version, on its own branch under spec/. Restoring from a single node's history restores that node. Restoring a whole revision restores every node it changed.

  3. Review and approve

    The diff shows the change back and any linked nodes, such as BIL-04. Once approved, SpecsGraph writes a new commit, here e40f6a8, and merging its pull request publishes it. The commits in between stay where they are.

  4. Record why

    Add a decision to the same proposal so nobody makes the same change again without knowing how it went.

Warning

Roll back in SpecsGraph, not with git revert

The graph is where the spec is edited, and the specsgraph/ folder is its published output. Reverting only the files in Git leaves the graph showing the newer version, and later publishes are written from the graph. Restore through SpecsGraph so both stay in step.

Read history with Git

Spec files are ordinary files in your repository, so the Git tools you already use work on them. Run these from the repository root.

TerminalShell
# Every spec revision on this branch, newest first
git log --oneline -- specsgraph/

# How ORD-13 changed over time, with the diff of each revision
git log -p --follow -- specsgraph/contexts/orders/requirements/ORD-13.md

# Who last changed each line of ORD-12
git blame specsgraph/contexts/orders/requirements/ORD-12.md

# ORD-12 as it was at a given commit
git show a1c9e02:specsgraph/contexts/orders/requirements/ORD-12.md

# What changed in the spec between two release tags
git diff v1.4.0 v1.5.0 -- specsgraph/

# Code commits that mention a requirement ID
git log --oneline --grep "ORD-12"

How revisions appear on your base branch depends on how you merge pull requests. A squash merge leaves one commit per proposal. A merge commit keeps the SpecsGraph commit and adds the merge on top. Either way, git log -- specsgraph/ lists them. Branches and pull requests has the details.

Next steps