121 lines
4.9 KiB
Markdown
121 lines
4.9 KiB
Markdown
---
|
||
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. 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. |
|