EZ-Template is the autonomous library all 6 Spartan teams use. When the library updates, your code might break. Or it might fix a bug that's been costing you matches. Knowing which is which is a programmer skill, not a guess.
Semantic Versioning — What 3.2.2 Means
EZ-Template uses semantic versioning: three numbers separated by dots, like 3.2.2. Each number means something specific.
3.x.x
MAJOR — breaking changes
The API has changed. Function signatures, class names, or behavior is different. Your old code may not compile, or worse, it may compile but behave incorrectly. Plan for code rewrites when this number changes.
x.2.x
MINOR — new features, backward-compatible
The library added new capabilities. Your existing code still works. You can ignore the new features or adopt them gradually. Safe to update during build season; test before competition.
x.x.2
PATCH — bug fixes only
A specific bug got fixed. No new features, no API changes. Updating should just make things work better — but patches occasionally introduce different bugs. Update during stable build periods; don't update mid-competition.
The Stability Principle
Stability beats features during competition season. A library version that's been tested over 10 scrimmages and 30 practice runs is more valuable than a new version with one bug fix you don't need.
This is the engineering version of the saying "don't fix what isn't broken": every library update introduces a small risk that something else breaks — even patch releases. The benefit must outweigh that risk.
⚠️
The single most common version-related failure is updating the library on Friday before a Saturday tournament. The team thinks "this fixes the bug we've been seeing," updates, doesn't test thoroughly, and discovers at competition that something else changed. Don't do this. Friday before competition is freeze day.
Why This Page Exists
This guide was written because EZ-Template ships new releases multiple times per season, and the question "should we update?" comes up regularly. Without a written policy, programmers either update too often (introducing instability) or never update (missing real bug fixes that would help). This page is the team's answer to that question.
The Six Things You Need To Know
What semantic versioning means — covered above.
How to read EZ-Template release notes — Tab 2: Reading Releases.
When to update vs when to wait — Tab 3: Season Calendar.
The actual update commands — Tab 4: How To Update.
What v3.2.2 specifically changed and whether you need it — Tab 5: v3.2.2 Specifics.
How to document your version choices in the engineering notebook — Tab 6: Notebook.
1 of 6
// Section 02
Reading EZ-Template Release Notes 🔎
Every EZ-Template release is announced on GitHub. The release notes follow a structure — once you know what to look for, you can decide in 60 seconds whether to update.
Each release has a tag (e.g., v3.2.2), a release date, and a list of changes. The most recent release is marked with a green "Latest" badge.
What To Look For (In Order)
1. Is this a major version bump?
If the first number changed (e.g., 2.x.x → 3.0.0), stop and read the entire release notes carefully. Major versions break things. The release will usually have a section titled "Breaking Changes" or "Migration Guide" with specific code that needs updating.
Action: never apply a major version update during the season. Schedule a 2–4 hour code-rewrite session in the offseason.
2. Is this a minor version bump?
If the second number changed (e.g., 3.1.x → 3.2.0), look for new features and read "What's Changed" closely. Your code should still compile, but the library behavior may have new defaults or extended capabilities.
Action: safe to apply during build season with thorough regression testing. Run all your existing autonomous routines on a real or mock field before declaring the update successful.
3. Is this a patch?
If only the third number changed (e.g., 3.2.1 → 3.2.2), the release notes will list specific bug fixes. Read each fix and ask: "Does this affect us?"
Action: only update if the fixed bug actually affects your team's code. If you're not seeing the bug, you don't need the fix — and the small risk of a regression isn't worth it.
Decoding the "What's Changed" Section
EZ-Template release notes use a structured format. Here's how to read each part:
You see
It means
Action
🐛 Bug fix in...
A specific bug was fixed. The bug is described after the icon.
Read the description. If it matches behavior you've seen, update. If not, skip.
⬆️ v3.X.Y
The version number itself was bumped. This is metadata, not a content change.
Ignore — the version bump itself isn't a code change.
✨ New feature: ...
New capability added. Won't break old code, but you'd need to write new code to use it.
Decide if it's worth adopting. If yes, plan a code-update session.
⚙️ Default changed: ...
An existing setting's default value changed. Your code may behave differently even though it didn't change.
Pay attention. Add the old default explicitly to your code so the change doesn't affect you.
❌ Removed: ...
An old API was removed. Code calling it will fail to compile.
Major version only. Find every reference in your code and update before applying.
The "Full Changelog" Link
At the bottom of each release page, you'll see something like:
Full Changelog: v3.2.1...v3.2.2
This link shows the line-by-line code differences between the two versions. You don't need to read this for patch releases — but for minor and major bumps, scroll through the diff to spot anything the release notes glossed over.
Worked Example — v3.2.2
Here's how to apply this process to the current latest, v3.2.2.
Major bump? No (still 3.x.x). → Don't need to read the whole thing.
Minor bump? No (still 3.2.x). → No new features to evaluate.
Patch? Yes (3.2.1 → 3.2.2). → Read the bug fix.
The single bug fix listed: "Right swings now work as expected when the autonomous routine is not mirrored."
Does this affect us? Only if you write non-mirrored autons AND have right-swing motions in them. If both are true, update. If not, skip.
💡
Total time to evaluate: ~60 seconds. That's the goal of this process. If you're spending more time deciding than the bug actually costs, you've failed the cost-benefit test.
2 of 6
// Section 03
When To Update vs When To Freeze 📅
The right time to update is not "when a new version drops." It's tied to where you are in the season. Here's the Spartan policy across all 5 phases.
Phase-By-Phase Update Policy
Phase A
Preseason build (Apr 27 – Jun 5). No competitions yet. Code is being written from scratch. Update freely — the library is one of many things being established.
UPDATE OK
Phase B
Summer break (Jun 5 – Jun 21). No competitions. Optional async work. Excellent time to apply major version bumps that need code rewrites — teams that engage have time to test thoroughly.
UPDATE OK
Phase C
Summer camp (Jun 22 – Jul 7). No competitions but daily build. Apply minor and patch updates with full regression testing. Avoid major version bumps mid-camp — finish camp on whatever version you started.
UPDATE WITH CARE
Phase D
Async (Jul 8 – Aug 12). Remote work, no shared in-person testing. Patch updates OK if the fix is needed. Avoid minor and major updates — debugging async without lab access is painful.
UPDATE WITH CARE
Phase E
Early season ramp (Aug 18 – Sep 5). First tournament Sep 5. Lock in the version you'll compete on by Aug 22. No updates after that lock date. If a critical bug shows up, it's a coach decision.
FREEZE
Comp Season
Sep 5 onward. Tournaments every 2–4 weeks. Library version is locked. Updates only between events with at least 1 full week of testing on real fields before the next competition.
FREEZE
The Lock Date Rule
For each tournament season, pick a lock date — usually 2 weeks before your first event. After the lock date:
The EZ-Template version is fixed for the season.
Code changes still happen, but the library underneath them does not.
If a critical bug shows up in EZ-Template, the coach decides whether to break the lock. The default answer is no.
The lock date and version are recorded in the engineering notebook.
Why This Calendar Exists
Library updates are like changing tires before a race. There's an optimal time (during routine maintenance) and a terrible time (the night before). Knowing which is which is what separates a smooth season from a chaotic one.
The single biggest reason teams lose competition matches isn't bugs in the library — it's changes the team made too close to competition. The Spartan policy biases hard toward stability over recency.
3 of 6
// Section 04
The Actual Update Workflow 🔧
Step-by-step. Run these commands in order; do not skip the test phase.
Pre-Update Checklist
Before running any update commands, verify all of these are true:
You're in the right phase. Phase A, B, or off-cycle — not within 2 weeks of competition. (See Tab 3.)
Your current code is committed to version control. If something breaks, you need to roll back.
You have a test plan. List the autonomous routines you'll run after updating.
Real or mock field is available. Don't test only on the brain — test on a field.
At least 30 minutes is available for testing. If you have 5 minutes, don't start.
Step 1 — Note The Current Version
Before updating, record what version you're currently on. Find it in your project.pros file or run:
# In your project directory:
pros c info-project
Look for the line with ez-template and note the version. Write it down on paper or in the notebook. This is the version you roll back to if the update breaks something.
Step 2 — Fetch The New Version
# Fetch a specific version (recommended):
pros c fetch ez-template@3.2.2# Or fetch the latest (less predictable):
pros c fetch ez-template
This downloads the version to your local cache but does NOT apply it to your project yet.
Step 3 — Apply To Project
pros c apply ez-template@3.2.2
This updates the library in your project. You should see a confirmation message indicating success.
Step 4 — Compile
pros mu
If compilation fails: stop. Read the errors. The most common cause is a function signature change — you'll see something like "no matching function for call to" in the error. Look up the new signature in the EZ-Template docs and update your code, or roll back (Step 7) if it's not worth fixing.
If compilation succeeds: proceed to testing. Don't assume success means the update worked — behavior changes can compile without errors.
Step 5 — Run The Test Plan
Run every autonomous routine on a real or mock field. Compare each one to its expected behavior. Document any differences.
Test
Expected
Actual
Pass?
Auton Routine 1 (Red Match)
Score 7 alliance pins, end clear of perimeter
(fill in)
(Y/N)
Auton Routine 2 (Blue Match)
Mirror of routine 1
(fill in)
(Y/N)
Auton Routine 3 (Skills)
10s sequence; ends at home corner
(fill in)
(Y/N)
Driver-control PID test (drive forward 24″)
Stops within ±1″ of target
(fill in)
(Y/N)
Driver-control turn test (turn 90°)
Stops within ±2° of target
(fill in)
(Y/N)
If any test fails, treat it as a regression. Roll back (Step 7) until you understand why.
Step 6 — Commit & Document
If all tests pass, commit the updated project.pros file with a clear message:
# Git commit message format:
"Update EZ-Template v3.2.1 → v3.2.2
- Reason: bug fix for non-mirrored right swings
- Tests passed: all 5 routines verified on practice field
- Rollback version available at commit a1b2c3d"
Add a notebook entry following the format in Tab 6.
Step 7 — Rollback (If Needed)
If anything broke and you need to revert:
# Apply the previous version (the one you noted in Step 1):
pros c apply ez-template@3.2.1# Or use git to reset:
git checkout HEAD~1 project.pros
Then run pros mu again to recompile with the old version. Test that auton routines work as they did before. Document the failure in the notebook so future programmers know not to retry the same update without addressing whatever broke.
⚠️
If you're panicking and can't remember the old version, check git history: git log -- project.pros shows every commit that touched the file. The previous commit's version is your rollback target.
4 of 6
// Section 05
v3.2.2 — What Changed and Should You Update? 🔎
The current latest release at the time of writing. One bug fix, no new features. Decision framework below.
What v3.2.2 Changed
Single bug fix from the EZ-Template v3.2.2 release notes:
🐛 Right swings now work as expected when the autonomous routine is not mirrored
In v3.2.1 and earlier, calling a right-swing turn on a non-mirrored auton could rotate the wrong direction or behave inconsistently. v3.2.2 fixes this so right swings work correctly regardless of whether the auton is mirrored.
The example project in the EZ-Template repo also clarified its tracking-wheel documentation in this release.
Does Spartan Need This Update?
Three questions to answer:
Do your auton routines use right swings? A swing is when one wheel pair drives forward while the other holds still — the robot pivots around the held side. If your routines only use straight drives and full turns, this bug never affected you.
Are any of your routines non-mirrored? A mirrored auton has two versions (red side runs as written, blue side runs flipped) using EZ-Template's mirror feature. A non-mirrored auton is hand-written for one specific side only.
Have you seen unexpected swing behavior? Look at your scrimmage logs — routines that turned the wrong direction or finished off-target on right swings.
Decision Tree
✅ Update If...
You answered yes to all three questions above.
You're in Phase A or B (preseason / summer break).
You have at least 30 minutes for the update + test cycle.
⚠️ Wait If...
You haven't seen the bug in practice (no broken right-swing behavior).
Your team only writes mirrored autons (the bug doesn't affect you).
You're close to a competition (within the lock window).
You haven't finished testing your current code on the current version.
❌ Don't Update If...
It's within 1 week of a tournament. Freeze the version, debug specific issues differently.
You're in the middle of a multi-week build sprint and the team can't spare testing time.
You're using EZ-Template features in ways that haven't been thoroughly regression-tested.
Spartan's Phase-A Recommendation
Most teams should update to v3.2.2 during Phase A. The bug is real, the fix is targeted, and you have time to test. Treat it as routine maintenance during a build week, not a rush.
Process:
One programmer per team applies the update on their robot first.
Run the test plan from Tab 4.
If all pass, the team can apply the update.
Document the update in the team notebook (template in Tab 6).
If failures appear, document the regression and roll back; flag for whole-team programmer meeting on Tuesday.
Every library update should leave a trace in the engineering notebook. This is also a strong topic for judge interviews — it shows technical maturity and process discipline.
Notebook Entry Template
Each EZ-Template version change adds an Appendix entry following this format:
[Date] EZ-Template Update: vX.Y.Z → vA.B.C
Reason for update: [Specific bug fix needed, new feature being adopted, scheduled offseason refresh, etc.]
Phase context: [Phase A/B/C/D/E and how many days until next competition.]
Pre-update version: [Old version, e.g., 3.2.1]
Post-update version: [New version, e.g., 3.2.2]
Tests run: [List of auton routines + driver-control tests, with pass/fail for each.]
Result: ["All tests passed, update committed" OR "Regression detected in [specific test], rolled back"]
Programmer: [Name of student who applied the update.]
Reviewer: [Name of student who verified the test results.]
Why This Goes In The Notebook
Three reasons:
Reproducibility. If a future student needs to recreate your competition build (laptop dies, new programmer joins mid-season), the notebook tells them exactly which version to use.
Debugging. If an auton starts behaving differently after a tournament, the notebook tells you whether the library version changed or not. Eliminates one variable from your debugging.
Judge interviews. Judges score teams on engineering process. A team that documents library version control is signaling that they take software discipline seriously — which separates them from teams that just "copy the code that worked last week."
Judge Interview Talking Points
If a judge asks about your software process, version management is a strong topic:
🎤
Interview line: “We treat EZ-Template like a versioned dependency, not a random download. Every version change is documented in our notebook with the reason for the update, the regression tests we ran, and the programmer who verified it. We have a written policy for when we update and when we freeze — you don't change tires the night before a race. Our most recent version change was [vX.Y.Z], applied during Phase [A/B/C], and we tested every auton routine on a real field before committing.”
🎤
Interview line: “Our team learned that mid-season library updates are how you lose tournaments. We have a lock date 2 weeks before our first competition; after that, the version is frozen. If a critical bug appears, it's a coach decision — the default answer is no. This policy came from our experience [or from learning from teams who shared this lesson] and it's saved us from at least one Saturday of debugging.”
STEM Connection
🧠
Software configuration management (SCM) is the engineering discipline of controlling and documenting library and tool versions. It's why airline software, medical devices, and self-driving cars don't randomly change behavior between deployments. The Spartan version-control policy is a middle-school version of the same discipline used in production engineering teams.
Cross-References
ez-setup — first-time EZ-Template install (different doc, different concern).