Leopoldo Rodríguez
be9011d341
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QCy5VHMVLkAmftYM6swWmx
153 lines
6.5 KiB
Markdown
153 lines
6.5 KiB
Markdown
---
|
||
title: "HBox_PCB — Guía Git para colaboradores externos (versión en inglés)"
|
||
tags: [project-drogheda, git, kicad, colaboradores, en]
|
||
date: 2026-09-15
|
||
project: Project Drogheda
|
||
author: 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](guia-git-es.md).
|
||
|
||
**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):
|
||
|
||
```bash
|
||
git clone ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git
|
||
cd HBox_PCB
|
||
```
|
||
|
||
HTTPS (if your network blocks port 222):
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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`. |
|