126 lines
4.6 KiB
Markdown
126 lines
4.6 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 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):
|
||
|
||
```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. 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`.
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## Historial de revisiones
|
||
|
||
| Versión | Fecha | Autor | Cambios |
|
||
|---|---|---|---|
|
||
| 1.0 | 2026-09-15 | Helgen Technologies | Guide for external collaborators (English). |
|