Helgen-Services/hbox-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
13a21883f7
hbox-docs/docs/git/git-guide-en.md

6.5 KiB
Raw Blame History

title tags date project author
HBox_PCB — Guía Git para colaboradores externos (versión en inglés)
project-drogheda
git
kicad
colaboradores
en
2026-09-15 Project Drogheda Helgen Technologies

HBox_PCB — Guide for External Collaborators

!!! note "Versión en inglés" Versión en inglés — la versión en español es Guía Git para colaboradores externos.

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 designs (Oct-2026): hbox-watchdog-v5.* (V5.6, Michelle's layout), hbox-watchdog-v57.* (V5.7, Leo → Michelle) and hbox-watchdog-v6.* (v6). v3-PROD, v4 and the tag v5.5-as-fabbed are historical: do not edit.
  • 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. When git pull reports CONFLICT on a KiCad file

It happens when you and someone else both saved the same .kicad_pcb or .kicad_sch starting from the same commit. Git cannot combine two boards: if it leaves <<<<<<<, ======= or >>>>>>> inside the file, KiCad can no longer open it ("Failed to load board"). That is what broke V5.6 and V5.7 in merge 40decf8 (19-Oct-2026).

Since 19-Oct-2026 the repository carries a .gitattributes: on a conflict in a KiCad file, git keeps your whole version (it opens fine in KiCad) and flags the file as conflicted, without writing markers. The other side's changes are still not included. So:

  1. Do not commit or push with a conflict pending. git status lists those files as both modified.

  2. If unsure which version to keep: git merge --abort (puts everything back as it was before the pull) and tell Leo.

  3. Once you have agreed which version stays, pick one whole side per file:

    git checkout --ours   hbox-watchdog-v57.kicad_pcb   # your version
git checkout --theirs hbox-watchdog-v57.kicad_pcb   # the server's version
git add hbox-watchdog-v57.kicad_pcb
git commit

    Whatever was left out is redone by hand in KiCad. Careful: during a git rebase they swap — --ours is the server's and --theirs is yours.

  4. Before pushing, confirm no markers are left (this must print nothing) and that the project opens in KiCad:

    git grep -n -E '^(<<<<<<<|>>>>>>>)' -- '*.kicad_*'

To avoid it: git pull when you start each session and git push when you finish — don't leave work unpushed overnight.

7. 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.

8. 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.

9. Questions

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

Historial de revisiones

Versión Fecha Autor Cambios
1.0 2026-09-15 Helgen Technologies Guide for external collaborators (English).
1.1 2026-10-19 Helgen Technologies New §6: what to do when git pull reports CONFLICT on a KiCad file; .gitattributes with merge=binary.