hbox-docs/docs/git/git-guide-en.md

HBox_PCB — Guide for External Collaborators

Project: EinarBoard / HBOX watchdog (Helgen Technologies) Repository: KiCad hardware design files only Contact: Leo Rodríguez — leo@helgen.tech

---

1. What this repository is

The complete KiCad design history of the HBOX watchdog board, versions v3 through v6.

• Active design: hbox-watchdog-v6.* — this is the only version under development.
• hbox-watchdog-v3/v4/v5.* are frozen history. Do not modify them.
• Files ending in -PROD are snapshots of boards that were actually fabricated. Never touch these.
• Symbol and footprint libraries (Drogheda-v6.kicad_sym, Drogheda-v6.pretty/, sym-lib-table, fp-lib-table) live inside the repo with project-relative paths, so a clone is self-contained — no external library setup needed.
• docs/ contains the EinarBoard v6 Copper Plan — Placement & EMC Guide (English and Spanish). Read its §0 (EMC laws) and §8 (master proximity table) before proposing any placement or routing change.

2. Getting access

1. Ask Helgen to create an account for you on the Git server git.helgen.online and to grant you access to Helgen-Services/HBox_PCB.
2. Log in to the web interface and add your SSH public key under your account settings.
3. Note that SSH runs on port 222, not 22.

3. Cloning

SSH (recommended):

git clone ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git
cd HBox_PCB

HTTPS (if your network blocks port 222):

git clone https://git.helgen.online/Helgen-Services/HBox_PCB.git

For a read-only review, a shallow clone is much faster (the repo carries 3D STEP/STL models and full history):

git clone --depth 1 ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git

4. Tooling

• KiCad 10.x is required. The project is saved in the KiCad 10 format.
  • Do not open the files with KiCad 9 or older.
  • Do not let a newer major version migrate/re-save the files without agreeing with Helgen first.
• Open hbox-watchdog-v6.kicad_pro; the schematic and PCB hang off it.

5. Ground rules — KiCad files and git

KiCad's .kicad_sch and .kicad_pcb are single large text files. Concurrent edits do not merge cleanly, so:

1. One editor at a time. Announce before you start editing, and say when you are done.
2. Pull before opening KiCad. Never pull while the project is open in KiCad. Close KiCad first, pull, reopen.
3. Never commit:
   • lock files (~*.lck)
   • backup files (*bak, *-bak*, autosave files)
   • *.kicad_prl (per-user display preferences — your local one will change constantly; leave it out of your commits)
   • fabrication outputs or reports you generated locally
4. Do not run "Update PCB from Schematic", global re-annotation, or library/format migrations unless that is the agreed task — they generate huge diffs that bury real changes.
5. Keep commits small and single-purpose.

6. Contribution workflow

Never commit to main directly.

# start from up-to-date main
git checkout main
git pull

# create your branch
git checkout -b review/<yourname>/<topic>     # e.g. review/ana/emc-g2

# ... work in KiCad, then close KiCad and check what changed
git status
git diff --stat

# stage only the intended files
git add hbox-watchdog-v6.kicad_pcb
git commit -m "v6 PCB: <what you changed> (<why>)"

# publish and open a Pull Request to main in the web interface
git push -u origin review/<yourname>/<topic>

Before opening the Pull Request, refresh your branch:

git fetch origin
git rebase origin/main

Helgen reviews and merges. Never force-push to main.

7. Review-only feedback (no file edits)

If your role is review rather than editing, do not modify files at all: open an Issue in the web interface. Reference parts by their reference designator (U25, C149, J12…) and, where relevant, the Copper Plan section number (e.g. "§8, U25 group"). Screenshots of the KiCad view are welcome.

8. Questions

Anything unclear — ask before pushing. A five-minute question is cheaper than untangling a bad merge of a 1.5 MB board file.