RobotGuide

Systems & software · topic D9 · 40 hours

Engineering workflow (Git / CMake / testing / CI)

Robot teams typically run five years behind internet companies in engineering practice. Whoever masters this stack walks in with a head start, because «can the robot actually move» is the hardest thing to automate.

Engineering stage · Intermediate
Algorithm · Hands-on System software · Proficient Embedded & controls · Hands-on Mechanical · Aware

Tools
Tools

What to learn

  • A minimal viable practice for Git branching strategy and code review
  • CMake project organization and dependency management (how to keep third-party libraries from fighting each other)
  • Unit tests, integration tests, and how to write a robot's «smoke test»
  • CI: every commit triggers an automatic build + a simulation run + a report, and a red light blocks the release

The lesson · plain words

Engineering discipline means «letting other people (and you, three months from now) take over your code». Git, CMake, tests, CI — all four serve the same thing: every change is traceable, verifiable, and revertible.

The classic symptom of poor engineering in robot projects: only one computer can build it, and only one person can change it.

Git: the discipline of branching and merging

Watch the figure: a feature branch finishes its edits → merge → hits a conflict (two people changed the same spot) → a human rules. A conflict is not git failing; it surfaces a requirement collision to you early.

Practical discipline for robot projects: main is always buildable and deployable; feature branches live no longer than a week; commits are small enough that «one commit says one thing»; never rewrite public history (force-pushing to main = career suicide).

Interactive figure · drag it and see

What this figure shows: a main branch and a feature-x branch diverging and merging — two people edit different regions of one file and git merges automatically, but when the same lines are edited twice git stops with «CONFLICT: config.yaml» and asks for a human ruling; after the resolve and commit, the merge completes and the branch lifecycle closes. Takeaway: commit small, merge often — conflicts are always smaller than you fear; as a team, pick rebase or merge and do not freelance.

CMake: describing build dependencies

CMake really says three things: which targets to build, what each target depends on, and by what standard to build (optimization level / warnings / standard version). Robot projects add one more: in ament_cmake (ROS 2), package.xml and CMakeLists must agree, or colcon falls apart mid-build.

Practical rules: separate build directories for Debug and Release; get third-party libraries via find_package or FetchContent, never hand-copy .so files; treat warnings as errors (-Wall -Wextra catches half the bugs early).

Testing: unit testing, the robot-project reality

Controllers are hard to unit test? Just split them: a trajectory generator can be tested as a pure function (endpoints in, waypoints out); attitude estimation can be fed recorded sensor data (replay tests); integration tests run in simulation (F1) — CI works without any real hardware.

The minimal useful combo: gtest unit tests + data replay tests + simulation smoke tests. Coverage numbers need not be chased, but every bug fix adds «one test that reproduces it» — a year later the test suite is the team's most valuable asset.

CI: a gatekeeper, not a decoration

CI does three things: a build matrix (multiple platforms/compilers), running tests, and deploying artifacts. One robot-specific step: verify firmware build artifacts (size, section layout) so «it flashed last time but is 2 KB over this time» never happens.

How deep to go: write one GitHub Actions yaml (build + test + stats); add lint tests to a ROS 2 package. Skip the K8s-level fireworks — the gatekeeper must first hold the gate.

Three questions — do you really get it?

1. When does a git CONFLICT appear?

  • AEvery merge conflicts
  • BThe branch went too long without merging
  • CTwo branches edited the same code and git cannot rule automatically
Show answer

C. git only escalates to a human when it cannot merge by itself. Small steps and frequent merges keep conflicts tiny.

2. In robot projects, what is a «replay test»?

  • AReplaying the git history
  • BRunning the simulation slowly
  • CFeeding recorded sensor data into the algorithm and asserting on the output
Show answer

C. Recorded-data replay tests the algorithm without real hardware or real time — the workhorse of robot CI.

3. What happens when CMakeLists and package.xml disagree?

  • Acolcon fails mid-build / dependencies go missing
  • BThey get fixed automatically
  • CJust a warning
Show answer

A. In the ament world the two manifests each govern one side; disagreement is a common source of ROS 2 build failures.

Keep going deeper

Links without a marker stay on this site; the rest point to the Chinese edition until its translation batch lands.

How it fails in the field

  • Releases are all manual; when something breaks there is no rollback — you hunt the last known-good binary from memory
  • Tests cover only the happy path; the exception branches have never once been executed

You have learned enough when

You can set up a «commit-to-build + simulation smoke test + report» pipeline for a ROS 2 project and demonstrate one red-light interception.

The Chinese edition carries the full topic page for Engineering workflow (Git / CMake / testing / CI), including the complete outline, depth requirements per career track, and further derivations: robotguide.dev/k/D9/.