---
title: "HBox_PCB — Guía Git para colaboradores externos"
tags: [project-drogheda, git, kicad, colaboradores]
date: 2026-09-15
project: Project Drogheda
author: Helgen Technologies
---

# HBox_PCB — Guía Git para colaboradores externos

[English version](git-guide-en.md).

Proyecto: EinarBoard / HBOX watchdog (Helgen Technologies)
Repositorio: únicamente archivos de diseño KiCad
Contacto: Leo Rodríguez — leo@helgen.tech

## 1. Qué es este repositorio

El historial completo de diseño en KiCad de la tarjeta HBOX watchdog, versiones v3 a v6.

- **Diseños activos (oct-2026):** `hbox-watchdog-v5.*` (V5.6, layout de Michelle), `hbox-watchdog-v57.*` (V5.7, Leo → Michelle) y `hbox-watchdog-v6.*` (v6). `v3-PROD`, `v4` y el tag `v5.5-as-fabbed` son históricos: no se editan.
- `hbox-watchdog-v3/v4/v5.*` son historial congelado. No los modifiques.
- Los archivos terminados en `-PROD` son instantáneas de tarjetas que ya se fabricaron. No los toques nunca.
- Las bibliotecas de símbolos y huellas (`Drogheda-v6.kicad_sym`, `Drogheda-v6.pretty/`, `sym-lib-table`, `fp-lib-table`) viven dentro del repositorio con rutas relativas al proyecto, así que el clon es autocontenido — no hay que configurar bibliotecas externas.
- `docs/` contiene el **Plan de Cobre EinarBoard v6 — Guía de colocación y EMC** (inglés y español). Lee su §0 (leyes de EMC) y su §8 (tabla maestra de proximidad) antes de proponer cualquier cambio de colocación o ruteo.

## 2. Obtener acceso

1. Pide a Helgen que te cree una cuenta en el servidor Git `git.helgen.online` y te dé acceso a `Helgen-Services/HBox_PCB`.
2. Entra a la interfaz web y agrega tu llave pública SSH en la configuración de tu cuenta.
3. Ten en cuenta que SSH corre en el **puerto 222**, no en el 22.

## 3. Clonar

SSH (recomendado):

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

HTTPS (si tu red bloquea el puerto 222):

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

Para una revisión de solo lectura, un clon superficial es mucho más rápido (el repositorio incluye modelos 3D STEP/STL e historial completo):

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

## 4. Herramientas

- **Se requiere KiCad 10.x.** El proyecto está guardado en el formato de KiCad 10.
  - **No** abras los archivos con KiCad 9 o anterior.
  - **No** dejes que una versión mayor más nueva migre o re-guarde los archivos sin acordarlo antes con Helgen.
- Abre `hbox-watchdog-v6.kicad_pro`; el esquemático y el PCB cuelgan de él.

## 5. Reglas de oro — archivos KiCad y git

Los `.kicad_sch` y `.kicad_pcb` de KiCad son archivos de texto únicos y grandes. Las ediciones concurrentes no se fusionan bien, así que:

1. Una sola persona editando a la vez. Avisa antes de empezar a editar y avisa cuando termines.
2. Haz pull antes de abrir KiCad. Nunca hagas pull con el proyecto abierto en KiCad. Cierra KiCad, haz pull, y vuelve a abrir.
3. **Nunca subas al repositorio:**
   - archivos de bloqueo (`~*.lck`)
   - respaldos (`*bak`, `*-bak*`, archivos de autoguardado)
   - `*.kicad_prl` (preferencias de vista por usuario — el tuyo cambia constantemente; déjalo fuera de tus commits)
   - salidas de fabricación o reportes generados localmente
4. **No ejecutes** "Update PCB from Schematic", re-anotación global, ni migraciones de biblioteca/formato salvo que esa sea la tarea acordada — generan diffs enormes que entierran los cambios reales.
5. Haz commits pequeños y de propósito único.

## 6. Si `git pull` marca CONFLICT en un archivo de KiCad

Pasa cuando tú y alguien más guardaron el mismo `.kicad_pcb` o `.kicad_sch` partiendo del mismo commit. Git **no puede** combinar dos tarjetas: si deja `<<<<<<<`, `=======` o `>>>>>>>` dentro del archivo, KiCad ya no lo abre ("Failed to load board"). Así quedaron V5.6 y V5.7 en el merge `40decf8` (19-oct-2026).

Desde el 19-oct-2026 el repositorio trae un `.gitattributes`: ante un conflicto en un archivo de KiCad, git deja **tu** versión completa (abre bien en KiCad) y marca el archivo como en conflicto, sin escribir marcadores. Aun así, los cambios del otro lado **no** quedan incluidos. Entonces:

1. **No hagas commit ni push** con un conflicto pendiente. `git status` muestra esos archivos como `both modified`.
2. Si tienes duda de con qué versión quedarte: `git merge --abort` (deja todo como estaba antes del pull) y avísale a Leo.
3. Si ya acordaron qué versión se queda, elige **un lado completo** por archivo:

   ```bash
   git checkout --ours   hbox-watchdog-v57.kicad_pcb   # tu versión
   git checkout --theirs hbox-watchdog-v57.kicad_pcb   # la del servidor
   git add hbox-watchdog-v57.kicad_pcb
   git commit
   ```

   Lo que se quedó fuera se rehace a mano en KiCad. Ojo: durante un `git rebase` se invierten — `--ours` es la del servidor y `--theirs` la tuya.
4. Antes de hacer push, confirma que no quedaron marcadores (este comando no debe imprimir nada) y que el proyecto abre en KiCad:

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

Para evitarlo: `git pull` al **empezar** cada sesión y `git push` al **terminar** — no dejes trabajo sin subir de un día para otro.

## 7. Flujo de contribución

Nunca hagas commit directo a `main`.

```bash
# parte de un main actualizado
git checkout main
git pull

# crea tu rama
git checkout -b review/<tunombre>/<tema>     # p. ej. review/ana/emc-g2

# ... trabaja en KiCad, luego cierra KiCad y revisa qué cambió
git status
git diff --stat

# agrega solo los archivos que quieres cambiar
git add hbox-watchdog-v6.kicad_pcb
git commit -m "v6 PCB: <qué cambiaste> (<por qué>)"

# publica y abre un Pull Request hacia main en la interfaz web
git push -u origin review/<tunombre>/<tema>
```

Antes de abrir el Pull Request, actualiza tu rama:

```bash
git fetch origin
git rebase origin/main
```

Helgen revisa y hace el merge. Nunca hagas force-push a `main`.

## 8. Retroalimentación de solo revisión (sin editar archivos)

Si tu papel es revisar en lugar de editar, no modifiques archivos: abre un Issue en la interfaz web. Refiérete a los componentes por su designador de referencia (`U25`, `C149`, `J12`…) y, cuando aplique, por el número de sección del Plan de Cobre (p. ej. "§8, grupo U25"). Las capturas de pantalla de KiCad son bienvenidas.

## 9. Dudas

Cualquier cosa que no esté clara — pregunta antes de hacer push. Una pregunta de cinco minutos cuesta menos que desenredar un mal merge de un archivo de tarjeta de 1.5 MB.

## Historial de revisiones

| Versión | Fecha | Cambios |
|---|---|---|
| 1.0 | 2026-09-15 | Guía para colaboradores externos. |
| 1.1 | 2026-10-19 | §6 nueva: qué hacer cuando `git pull` marca CONFLICT en un archivo de KiCad; `.gitattributes` con `merge=binary`. |