---
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ño activo: `hbox-watchdog-v6.*`** — es la única versión en desarrollo.
- `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. 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`.

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

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