How we ship Setcon software

The big picture

Three layers of branches. Everyone agrees on which layer their work belongs in.

Why this way?

Our software runs in places where breakage is expensive — on customer controllers in the field, on cloud EMS servers that customers depend on, on industrial panels that are hard to reach. We can't just push to a single line and hope. We need an integration playground separate from what's deployed to production. Hence two protected lines: main for what's running, dev for what's next.

The model applies whether you're working on:

• Controller code — the CODESYS / Node.js firmware that runs on customer-deployed energy controllers
• Cloud platforms — the EMS, monitoring, or customer-facing services hosted on Setcon servers
• Internal tools — commissioning utilities, diagnostic tools, brand assets, anything else under version control

Before you start

One-time setup. Each row links to a detailed guide in the Setup guides section below.

First-time setup

The actual sequence we walk new teammates through — sitting next to them at their machine. Each step has a checkpoint; pause and verify before moving on.

Commands shown in PowerShell (Windows default). They all work in Git Bash too, with slightly different path syntax (/c/Users/<you> instead of C:\Users\<you>).

1. Pre-flight: what's already installed?

   Open PowerShell (Win + R → type powershell → Enter):

   git --version       # expect git version 2.x
   node --version      # expect v20.x or later

   If either says "not recognized", install it before going further:

   • Git: git-scm.com/download/win — see Install Git + Git Bash for recommended options
   • Node.js: nodejs.org — pick the LTS download

   Re-run the checks above before continuing.

2. Configure your git identity

   So every commit you make is stamped with your name and links to your GitHub profile:

   git config --global user.name "Your Full Name"
   git config --global user.email "your-github-email@example.com"

   Use the email associated with your GitHub account. Verify:

   git config --global --list

   Should show user.name=... and user.email=... among the output.

3. Generate a Personal Access Token (PAT)

   GitHub's password replacement for command-line operations. Created once, stored by Windows Credential Manager after first use.

   1. Sign in to GitHub in any browser
   2. Visit github.com/settings/tokens → Personal access tokens (classic) → Generate new token (classic)
   3. Fill in:
      • Note: setcon-<your-laptop>
      • Expiration: 90 days
      • Scopes: tick repo (full control of private repos)
   4. Click Generate token → copy it immediately (GitHub only shows it once)
   5. Paste it somewhere temporary (Notepad is fine) until step 4 below
   If you lose the token

   Don't panic — just regenerate. The old one is invalidated automatically. Tokens are disposable.

4. Pick a projects folder and clone the repo

   Decide where you'll keep Setcon projects. Common choice: C:\Users\<you>\projects\.

   # Create the folder if it doesn't exist
   mkdir C:\Users\<you>\projects -Force
   cd C:\Users\<you>\projects
   
   # Clone (replace <repo> with the actual repo name)
   git clone https://github.com/setcon-za/<repo>.git
   cd <repo>
   git checkout dev

   The clone triggers an authentication prompt — a Windows dialog pops up. Pick the Token option, enter your GitHub username, paste the PAT as the password. Credential Manager remembers it after that.

   Verify:

   git status            # expect "On branch dev"
   git log --oneline -5  # expect a list of recent commits

5. Install dependencies

   npm install

   Pulls down node_modules for every workspace. Takes 1–2 minutes. Expect output like "added 200+ packages, 0 vulnerabilities".

6. Smoke-test by running the project

   Each repo has its own dev / build commands. For the controller HMI:

   npm run dev -w packages/frontend

   Vite starts and prints Local: http://localhost:5173/. Open that URL in your browser — you should see the HMI render with the dark theme. If yes, your environment is fully working.

   Press Ctrl+C in PowerShell to stop the server.

   Port already in use?

   If 5173 is busy (someone else on the same machine, or a previous session that didn't exit cleanly), Vite automatically picks 5174. That's normal — just visit the URL it prints.

7. Open the workflow guide

   In File Explorer, navigate to your cloned repo → docs\workflow-guide.html → double-click. Opens in your default browser.

   Skim the Daily workflow section — that's the loop you'll run for every change going forward.

8. Your "Hello PR"

   The single best way to internalise the workflow: do it once with a tiny, real change. Suggestions:

   • Fix a typo you spot in any doc
   • Add your name to a CONTRIBUTORS.md
   • Tighten an unclear comment in code you read

   Then follow the standard PR loop:

   git checkout dev
   git pull
   git checkout -b fix/<short-description>
   # make your change in an editor, save
   git add <the-file>
   git commit -m "fix: <short-description>"
   git push -u origin fix/<short-description>

   Open the PR via the URL git prints. A teammate reviews + approves. You squash-merge + delete the branch. Pull dev locally.

   You're now a contributor. From here, every change follows that same loop.

Daily workflow

The loop you'll repeat hundreds of times. Five moves.

1. Sync with the latest dev

   Pulls down anything teammates have merged since you last worked.

   # Morning ritual — never skip this
   git checkout dev
   git pull

   Why: branching off a stale dev means you'll probably hit merge conflicts later. 30 seconds now saves 30 minutes on Friday afternoon.

2. Branch off dev with a descriptive name

   Pick a prefix matching the kind of change you're making.

   Prefix	When	Example
   feature/	New functionality	feature/dispatch-optimisation
   fix/	Bug fix	fix/login-redirect-loop
   refactor/	Restructure, no behaviour change	refactor/extract-shared-charts
   chore/	Tooling, deps, config	chore/upgrade-vite-7
   docs/	Documentation only	docs/add-onboarding-guide

   git checkout -b feature/<your-topic>

   Your terminal prompt should change to show the new branch in parentheses.

   

   FIG 1Real terminal: sync dev, branch off, stage a new file

3. Code, commit, push — small chunks

   Commit every time you finish a coherent slice of work. Don't wait until the whole feature is done. One concept per commit.

   # Stage just the files you intend to commit
   git add path/to/changed-file.ts
   
   # Commit with a conventional message
   git commit -m "feat: Add <short description of what this adds>"
   
   # First push needs -u to set up tracking; after that just `git push`
   git push -u origin feature/<your-topic>

   Conventional commits

   Subject ≤ 70 chars. Start with one of: feat:, fix:, chore:, refactor:, docs:, ci:, test:, perf:. Imperative mood ("Add", not "Added"). Body explains why, not what.

   

   FIG 2After push: GitHub prints the PR creation URL you click next

4. Open a PR targeting dev

   Once your feature is in a reviewable state, push your final commits and open the pull request. The push output prints a URL — click it.

   git push
   # → https://github.com/setcon-za/<repo>/pull/new/feature/<your-topic>

   On the PR form, confirm base = dev and fill in:

   • Title: same conventional format (e.g. feat: Add <short description>)
   • What changed — 1–2 sentences
   • Why — the user-facing reason
   • How to verify — steps to test locally
   • Screenshots for any UI change

   Click Create pull request.

   

   FIG 3The PR creation form — confirm base = dev before clicking create

5. Wait for CI + review, address feedback, merge

   Within ~30 seconds, the project's CI checks kick off (typically a build + tests; each repo defines its own in .github/workflows/). While they run, a teammate picks up the review.

   • CI running   Yellow dot — build / tests in progress
   • CI passed   Green check — all checks satisfied
   • CI failed   Red x — fix the issue, push again, CI re-runs

   The merge box on the PR is your status dashboard. Here's what it looks like right after the PR opens — review block, CI still queued, the merge button greyed out:

   

   FIG 4Composite status: review block + CI queued + merge greyed out

   ~17 seconds later the build finishes. The CI section turns green but the review requirement still blocks — protection working exactly as designed:

   

   FIG 5CI green ≠ merge unlocked. Review requirement still blocks.

   Once you have an approval (or, while working solo, you tick the bypass option), the squash-merge button activates. Confirm the squash message and merge. GitHub immediately shows the merged state:

   

   FIG 6Merged. Click Delete branch to clean up the remote.

   Then locally:

   git checkout dev
   git pull
   git branch -D feature/<your-topic>

   Your dev fast-forwards to the squashed merge commit, and your local feature branch is gone. The new commit is visible at the top of git log alongside every other merged PR:

   

   FIG 7Back on a clean dev. The history reads like a changelog.

   You're back at the start of the loop. Time for the next task.

Code review

The single most important part of a team workflow. Two angles — the author and the reviewer.

How to leave a review on GitHub

1. Open the PR → Files changed tab
2. Hover the gutter on any line → click the + icon → leave a comment
3. For "change this to that" feedback, use a suggestion block (the ± icon) — the author can apply it with one click
4. When done, click Review changes at the top right
5. Choose: Approve, Comment (questions only, no block), or Request changes (block until addressed)

Merge conflicts

What happens when two PRs touch the same lines. Sounds scary the first time. It's fine.

The scenario

You and a teammate both edited the same file on different branches. They merged first. Your PR now shows a red banner: "This branch has conflicts that must be resolved."

Resolving locally

# 1. Switch to your branch and pull the latest dev into it
git checkout feature/your-thing
git fetch origin
git merge origin/dev

# 2. Git tells you which files conflict — open them in your editor
#    You'll see <<<<<<< HEAD ... ======= ... >>>>>>> origin/dev
#    markers around the conflicting regions.

# 3. Edit each conflict to keep the correct final code. Delete the markers.

# 4. Stage the resolved files and finish the merge
git add path/to/resolved-file
git commit -m "chore: Resolve merge with dev"

# 5. Push — the PR auto-updates and CI re-runs
git push

Working with Claude Code

Claude Code is an AI pair-programmer that lives in your terminal. It reads the repo, edits files, runs builds, and commits — like another developer on your team.

The rules of engagement

• Open Claude Code from your feature/<topic> branch. Claude commits to whatever branch you're on. Never run it from dev or main directly.
• Claude reads CLAUDE.md automatically. That file is the project-wide context — domain glossary, file map, conventions. Keep it accurate.
• Review every diff before pushing. Claude is fast and usually right, but it doesn't know everything. git diff before git push is your safety net.
• If Claude proposes something against convention, push back. The convention wins. Tell Claude what's wrong and ask it to retry.

Good things to ask Claude for

Releases

The rare moment when dev gets promoted to main and a customer-deployable version is born.

When to release

• A logical group of features is complete on dev
• Integration testing passed
• A customer deployment is planned (or you want a clean checkpoint)

The release process

1. Confirm dev is shippable

   Pull the latest dev, run a clean build, do a smoke test of the project locally.

   git checkout dev
   git pull
   # Then run the project's build + local smoke test
   # (each repo has its own commands — see its README)

2. Open the release PR: dev → main

   On GitHub, set base = main, compare = dev. Title: Release v0.4 — <theme>. Description is the changelog — group commits by feat:, fix:, refactor:, etc.

3. Get approval + merge

   Use Merge commit here, not Squash — preserves the dev history on main so an engineer can later trace which feature PR added what.

4. Tag the merge commit

   git checkout main
   git pull
   git tag -a v0.4-<theme> -m "Release v0.4 — short summary"
   git push --tags

   On GitHub: Releases → Draft a new release → pick the tag → write release notes → publish.

5. Deploy the tag to production

   Deploy the tagged version to whatever production target this repo serves — customer controller hardware, cloud server, internal panel, etc. The tag name is your reference point: if a bug is reported later, check out that tag to reproduce the exact deployed state.

Hotfixes (the rare exception)

Production (a customer controller, a cloud service, etc.) is on v0.4 and a critical bug surfaces. You can't wait for the next normal release cycle. Branch off main, fix, ship, then back-port to dev.

# 1. Branch off main (NOT dev)
git checkout main
git pull
git checkout -b hotfix/<short-description>

# 2. Fix the bug, commit
git commit -m "fix: <what the fix does>"

# 3. Push and open a PR targeting main (not dev)
git push -u origin hotfix/<short-description>

After the PR merges to main:

• Tag the new release (e.g. v0.4.1)
• Also open a PR merging main back into dev so the fix doesn't get lost when dev next releases
• Deploy v0.4.1 to the affected customer

Setup guides

One-time setup steps, each as a collapsible block. Work through them in order on a new machine.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

git config --global --list

Abbreviations

A quick reference for all the abbreviations used in this guide — useful if you are reading this for the first time.

Quick reference

Print this page or pin the section. The 10 commands that cover 95% of your day.

Conventional commit prefixes

Where to look for help

Each Setcon repo follows the same convention — look in these files of whichever project you're in:

If a doc you need isn't there, write it — that's a valid PR.