Hardware Revision Control

Hardware Revision Control is a git-style version control system for hardware design files, built into S3Suite. Use it to track every revision of your schematics, PCB layouts, firmware sources, and mechanical CAD over time, without juggling email attachments, Dropbox folders, or shared drives named "rev_B_FINAL_v2".

---

When you need it

Anytime more than one engineer touches a design file, or any time you need to answer "which version of this schematic shipped on Lot 2024-001?" three years from now, you need revision control. The feature is designed around two operational truths:

• Hardware design files are binary. A KiCad project, a SolidWorks part, an Altium PCB cannot be merged the way source code can. Revision control here is about immutable snapshots, not branch merging.
• Manufacturing needs a frozen file set. Engineering keeps evolving the design; manufacturing needs to know exactly which commit shipped on each lot. The Release concept links the two.

---

Concepts

Tip: Do not try to put everything in one repo. One repo per discipline keeps history clean and lets different teams commit on their own cadence.

---

Before you start

• Install the desktop app. Browsing history and downloading individual blobs works in any browser, but committing changes or restoring an older revision to disk needs the desktop app. See Desktop app and updates for download + auto-update info.
• Decide your repo structure. Most projects split into: one schematic repo, one PCB repo (often combined with schematic if the EDA tool stores them together), one firmware repo, one mechanical repo. Keep BOM in its own repo only if you treat it as a binary artifact; otherwise the BOM module in the Engineering Suite is a better fit.
• Settle on naming. Repo names appear everywhere. Pick something a vendor would recognise, like "Mainboard schematic" rather than "schematic_v3_actual".

---

Quick start: your first commit (10 minutes)

This walkthrough creates a repo, makes the first commit from your local design folder, and shows the result in the browser.

1. Create the repo

1. Open your project
2. In the sidebar, go to Engineering → Revision Control
3. Click New Repo
4. Fill in:

- Name - short and recognisable (e.g. "Mainboard schematic") - Tool stack - pick one: KiCad, Altium Designer, Autodesk Eagle / EasyEDA, Autodesk Fusion 360, SolidWorks, Mixed, or Other - Description - optional (e.g. "v1 schematic for the mainboard project, KiCad 8")

1. Click Create

You land on the repo detail page with an empty commit history and a "No commits yet" message.

2. Commit changes from the desktop app

1. Open the desktop app (same project, same login)
2. Navigate to the same Revision Control page inside the project
3. Click into your new repo
4. Click Commit changes (only visible inside the desktop app)
5. In the modal, click Browse and pick the local folder that contains your design files
6. The app scans the folder, hashes every file, and shows a diff against HEAD:

- Added files (green) - Modified files (yellow) - Deleted files (red) - Renamed files (blue)

1. Fill in:

- Message - short summary (e.g. "Initial schematic for mainboard rev A") - ECO number - optional (e.g. "ECO-2026-014") - Risk level - Low / Medium / High / Critical - Manufacturing impact - None / Minor / Major / PCB revision needed

1. Click Commit
2. The app uploads only the missing blobs (existing blobs deduplicate) and writes the commit document

When the upload finishes you see a success toast and the new commit appears at the top of the repo's history.

3. View the commit in the browser

1. Switch back to your browser (or stay in the desktop app, the UI is the same)
2. Refresh the repo detail page
3. The new commit is at the top of the history with your message, ECO, author, and the file count
4. Click the commit row to open the commit detail page, which shows the full file tree and lets you download individual blobs

Note: If you do not see the commit, check that the upload finished (the modal closes when done). The web UI may take 1-2 seconds to refresh after a large commit.

---

Workflow: cut a release for manufacturing

A release pins one commit per repo into a single named cut, locks the file set, and gives manufacturing a stable target to build against.

1. Go to Engineering → Revision Control → Releases
2. Click New Release
3. Fill in:

- Name - e.g. "V1.2 - Rev B" - Description - what is new, what to expect on the line - Initial status - Draft (default) or Released

1. For each repo in the project, the modal pre-selects the head commit. To pin an older commit instead, click the dropdown and pick from the repo's commit history.
2. Click Create Release

You land on the release detail page showing one pinned commit per repo, with the author, message, and date of each.

Locking a release

A release in Draft status can have its commit pins edited. Once you change status to Released, the pins are frozen forever.

1. On the release detail page, click Mark as Released
2. Confirm the dialog warning
3. The release is now immutable. Editing would require cutting a new release.

Note: Locked releases cannot be deleted either. The audit trail is permanent by design. That is what makes the as-built record trustworthy.

Linking a production lot to a release

1. Open the production lot (Manufacturing → Production Lots → click the lot)
2. In the Release field, pick the release you just cut
3. Save

From now on, every device in that lot back-references the release. Five years later you can pull any device serial and know exactly which schematic / firmware / mechanical commits shipped in it.

---

Workflow: restore an older revision to your local disk

When you need to rebuild an older revision (warranty repair, certification re-run, customer asking for the v1 firmware), restore the commit to a local folder.

1. Open the commit detail page for the revision you want
2. Click Restore to local folder (only visible in the desktop app)
3. Pick a destination folder (empty, or one you do not mind overwriting)
4. The app downloads every blob and writes the file tree exactly as it was committed
5. Open the restored folder in your EDA or CAD tool and you have the exact design that shipped

Note: Restoring does NOT change the repo state. The HEAD commit on the server is untouched. You are pulling a historical snapshot to disk.

Tip: Restore to a new folder, not over your working copy. That way your in-progress changes are not overwritten.

---

Workflow: handing off to a contract manufacturer

Vendors should always receive a release, never a running commit history.

1. Cut the release as described above
2. Mark it Released to lock the pins
3. Open the release detail page
4. Click Send to Vendor (also reachable from any variant page that uses this release)
5. The Send-to-Vendor flow attaches the frozen file set from each pinned commit, not the live engineering folder. See Manufacturing Vault for the underlying file flow.

The vendor receives one immutable bundle. If a change is needed later, you cut a new release and re-send. The old release stays in the audit trail.

---

Workflow: managing review status

Each commit carries a review status that gates how it shows up in vendor-facing flows.

To change a commit's review status:

1. Open the commit detail page
2. Click the Review Status dropdown in the right rail
3. Pick the new status

Tip: Only mark a commit "Review Done" after a second engineer has independently checked the changes. The status is visible on the release and to vendors, so it is the social contract for what is shippable.

---

Reference

Tool stacks supported

The dropdown when creating a repo offers these options. Pick the one that matches the bulk of the files in the repo.

• KiCad - open-source EDA
• Altium Designer - full proprietary EDA
• Autodesk Eagle / EasyEDA - Eagle legacy or EasyEDA exports
• Autodesk Fusion 360 - mostly mechanical
• SolidWorks - assemblies and parts
• Mixed - a repo that genuinely contains multiple tool stacks (use sparingly)
• Other - anything else (Cadence, Mentor, KiCad legacy projects, etc.)

Web vs Desktop

Common pitfalls

• "My commit shows zero files changed." The desktop app diffs against HEAD using content hashes. If your local files are byte-identical to the last commit, there is genuinely no change. Modifying a file then reverting the edit produces zero diff.
• "The upload is slow on a large project." First commits are slow because every blob is new. Subsequent commits only upload changed blobs, so they are much faster.
• "I locked the wrong commit into a release." Releases cannot be un-locked. Cut a new release with the correct pins. The wrong release stays in history but you ignore it.
• "My vendor says the file is corrupted." Confirm they downloaded from the Release, not from a stale email. The release file set is hash-verified end to end.

---

Related docs

• Engineering Suite -the broader engineering surface
• Manufacturing Vault -how Engineering files reach Manufacturing
• Desktop app and updates - install + auto-update flow for the desktop app
• Risk Management -pair revision control with explicit risk tracking on design changes