Guía del nuevo desarrollador — De cero a primera MR

Bienvenido a Wiedii. Esta guía es un tutorial secuencial: sigue los pasos en orden y al final tendrás la máquina configurada, entenderás el flujo de trabajo del equipo y habrás abierto tu primera Merge Request real.

Tiempo estimado: 60–90 minutos en una máquina limpia. Sistema operativo: macOS.

⚠️ Antes de empezar: asegúrate de tener los accesos listados en los prerrequisitos.

---

Prerrequisitos

| Acceso | Para qué | A quién pedirlo | |--------|----------|-----------------|| | Cuenta GitLab | Clonar repos, abrir MRs, CI | TL | | Microsoft Teams | Canal del equipo de ingeniería | TL / RRHH | | Correo corporativo (@wiedii.co) | Comunicaciones formales | RRHH |

Confirma acceso a https://gitlab.wiedii.co antes de continuar.

---

La filosofía de instalación en Wiedii

Homebrew instala herramientas del sistema. mise gestiona versiones por proyecto.

• Homebrew — gestor de herramientas del sistema: CLIs, apps de escritorio, utilidades. Nada se instala con curl | bash ni descargando instaladores.
• mise global (~/.config/mise/config.toml) — runtimes de lenguaje disponibles en todo el sistema (bun, node, python, uv). Se replican en cada máquina nueva.
• mise por proyecto (mise.toml) — versiones exactas por repo. Sobreescriben el global. mise run setup configura el entorno completo.
• OrbStack — runtime de contenedores y Kubernetes. Reemplaza a Docker Desktop y Podman (ambos no autorizados).

Ver gestion-herramientas-brew-mise y herramientas-por-rol para la guía completa de herramientas.

---

Fase 1 — Preparar la máquina

1.1 Homebrew

brew --version   # verificar si ya está

# Si no está (el único curl | bash de Wiedii — no hay alternativa en macOS):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Apple Silicon (M1/M2/M3/M4):
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile && source ~/.zprofile

1.2 Configurar mise global

Copiar el config global de mise con los runtimes estándar de Wiedii:

mkdir -p ~/.config/mise

cat > ~/.config/mise/config.toml << 'EOF'
[tools]
bun    = "1.3.14"
node   = "24.16.0"
pnpm   = "11.2.2"
python = "3.14.5"
uv     = "0.11.16"

[settings]
lockfile = true
EOF

cd ~/.config/mise && mise install --yes   # instalar todos los runtimes globales
cd -

Verificar:

bun --version    # ✅ 1.3.14
node --version   # ✅ v24.16.0
python --version # ✅ Python 3.14.5

1.3 Herramientas esenciales de desarrollo

# Gestión de versiones por proyecto
brew install mise

# Flujo de trabajo Git
brew install git git-flow-next

# GitLab CLI — interactuar con gitlab.wiedii.co desde terminal
brew install glab

# Herramientas de terminal
brew install jq yq bat eza fd ripgrep tree starship

# Runtime de contenedores (Docker/Kubernetes) — reemplaza Docker Desktop
brew install orbstack

# Fuente con iconos para la terminal
brew install font-jetbrains-mono-nerd-font

Verificar instalaciones:

git flow version   # ✅ git-flow-next x.y.z
mise --version     # ✅ mise x.y.z
glab --version     # ✅ glab x.y.z
docker context show   # ✅ orbstack

Para la lista completa de herramientas por rol (backend, devops, etc.) ver herramientas-por-rol.

1.4 Configurar el shell (zsh)

Aplicar la configuración estándar de Wiedii para el shell. Ver configuracion-zsh para el contenido completo de cada archivo.

Resumen de los archivos a configurar:

Archivo	Qué va ahí
~/.zshenv	PATH base del sistema
~/.zprofile	Activación de brew, mise, OrbStack, Starship
~/.zshrc	Completions (glab, kubectl, gh, aws), aliases, typeset -U PATH

Después de guardar los cambios, los terminales ya abiertos no se actualizan solos. Cada terminal cargó su configuración al abrirse y no vuelve a leer el archivo automáticamente. Para aplicar los cambios:

exec zsh   # recarga el shell actual — ejecutar en CADA terminal abierta
# El alias "reload" hace lo mismo una vez que el config esté cargado

Abrir un terminal nuevo (o ejecutar exec zsh en el actual) y verificar:

echo $SHELL   # ✅ /bin/zsh
starship --version   # ✅ starship x.y.z

Si tienes varias ventanas o pestañas abiertas, ejecuta exec zsh en cada una. Las sesiones SSH activas también necesitan exec zsh o reconectar. Ver configuracion-zsh para la explicación completa.

1.5 Git — configuración global

git config --global user.name  "Tu Nombre"
git config --global user.email "tunombre@wiedii.co"
git config --global merge.ff false
git config --global pull.rebase true

1.6 Clave SSH para GitLab

# Generar si no tienes una
ssh-keygen -t ed25519 -C "tunombre@wiedii.co"

# Copiar al portapapeles
cat ~/.ssh/id_ed25519.pub | pbcopy

Añadirla: https://gitlab.wiedii.co → avatar → Edit profile → SSH Keys → pegar → Add key

ssh -T git@gitlab.wiedii.co   # ✅ Welcome to GitLab, @tunombre!

1.7 Autenticar glab

glab auth login --hostname gitlab.wiedii.co
# Protocolo: HTTPS
# Token: gitlab.wiedii.co → Edit profile → Access Tokens
# Scopes requeridos: api, read_repository, write_repository
# Validez: máximo 3 meses — cada dev es responsable de rotar su token antes de que expire

glab auth status   # ✅ Logged in to gitlab.wiedii.co as @tunombre

# Desactivar telemetría — obligatorio
glab config set telemetry false
glab config get telemetry   # ✅ false

🔐 glab guarda el token en el keychain del sistema. Nunca escribas el token en archivos del vault. Ver glab para más detalle.

---

Fase 2 — Tu primer repositorio

Regla de ubicación: todos los repositorios Wiedii deben vivir en ~/Docker/. Nunca en ~/Documents/, ~/Desktop/ ni cualquier carpeta bajo iCloud — iCloud puede corromper el índice de git y generar conflictos silenciosos.

mkdir -p ~/Docker
git clone git@gitlab.wiedii.co:wildcat/wiedii-dev-onboarding.git ~/Docker/wiedii-dev-onboarding
cd ~/Docker/wiedii-dev-onboarding
mise run setup

mise run setup hace en orden: instala todas las herramientas del mise.toml → ejecuta lefthook install automáticamente (via [hooks].postinstall) → bun install si hay package.json. Un comando, entorno completo, funciona para cualquier stack.

# Verificar
mise list                  # herramientas activas en este directorio
lefthook run pre-commit    # ✅ sin errores en repo limpio
bun --version              # versión del proyecto (no del sistema global)
git remote -v              # ✅ origin → git@gitlab.wiedii.co:wildcat/wiedii-dev-onboarding.git

---

Fase 3 — El flujo de trabajo diario

Git Flow con MRs obligatorias. Nunca push directo a main o develop.

3.1 Ramas

Rama	Propósito	Push directo
main	Producción	❌ Solo MR
develop	Integración	❌ Solo MR
feature/*	Nueva funcionalidad	✅ Tu rama
release/*	Preparación de release	❌ Solo MR
hotfix/*	Corrección urgente	❌ Solo MR

3.2 Inicializar git-flow (una vez por clon)

git flow init --preset=classic --defaults

# Wiedii usa tags sin prefijo 'v' (1.2.0, no v1.2.0) — ajustar tras init:
git config gitflow.branch.release.tagprefix ""
git config gitflow.branch.hotfix.tagprefix ""

3.3 Ciclo completo de una feature

# 1. Partir de develop actualizado
git switch develop && git pull origin develop

# 2. Crear rama
git flow feature start TK0001-max-tres-palabras

# 3. Trabajar y hacer commits
git add .
bun commit   # wizard: tipo → scope → descripción

# 4. Actualizar desde develop (el preset classic hace rebase automáticamente)
git flow update

# 5. Publicar la rama y abrir la MR en un solo comando
git flow publish \
  -o merge_request.create \
  -o merge_request.target=develop \
  -o "merge_request.title=feat(scope): descripción [TK0001]"

El pipeline de CI arranca automáticamente. Si falla, corrige, haz commit y repite git flow publish — la MR se actualiza. Nunca squash — Wiedii usa merge commits.

3.4 Comandos shorthand de git-flow-next

git flow update    # actualiza la rama actual desde su padre (rebase)
git flow publish   # publica la rama actual al remote
git flow delete    # elimina la rama actual
git flow rename nuevo-nombre   # renombra la rama actual
git flow overview  # estado completo del repo: ramas, ahead/behind, health

---

Fase 4 — Tu primera contribución

git switch develop && git pull origin develop
git flow feature start onboarding-tunombre

echo "- Tu Nombre (@tunombreusuario) — $(date +%Y-%m-%d)" >> CONTRIBUTORS.md
git add CONTRIBUTORS.md
bun commit   # type: docs | scope: contributors | description: add tunombre

git flow publish \
  -o merge_request.create \
  -o merge_request.target=develop \
  -o "merge_request.title=docs(contributors): add tunombre to contributors list"

Pide a tu TL que apruebe la MR. MR mergeada = bienvenido al equipo. 🎉

---

Referencia rápida

Acción	Comando
Actualizar develop	git switch develop && git pull origin develop
Nueva feature	git flow feature start <id-descripcion>
Commit interactivo	bun commit
Actualizar rama desde padre	git flow update
Publicar + crear MR	git flow publish -o merge_request.create -o merge_request.target=develop -o "merge_request.title=..."
Solo publicar (sin MR)	git flow publish
Estado del repo	git flow overview
Ver mis MRs	glab mr list --author @me
Ver estado del pipeline	glab pipeline status

---

Troubleshooting

mise run setup falla:

mise trust && mise install --yes
bun install
lefthook install
# Reportar el error exacto al líder a cargo

El pre-commit hook rechaza el commit:

lefthook run pre-commit   # ver el error exacto → corregir → git add . → bun commit

ssh -T git@gitlab.wiedii.co dice "Permission denied":

ssh-add ~/.ssh/id_ed25519 && ssh -T git@gitlab.wiedii.co

glab auth status muestra error de hostname:

glab auth login --hostname gitlab.wiedii.co

docker no funciona / socket no disponible:

open -a OrbStack   # asegurarse de que OrbStack está corriendo

bun no se encuentra fuera del proyecto: correcto y esperado — ver gestion-herramientas-brew-mise.

---

Próximos pasos

Recurso	Qué aprenderás
herramientas-por-rol	Herramientas adicionales según tu rol (backend, devops)
configuracion-zsh	Detalles completos del setup del shell
SOLID DRY KISS	Principios de diseño del código Wiedii
gestion-herramientas-brew-mise	Filosofía completa de gestión de herramientas
git-flow	Git Flow completo: releases, hotfixes, orden de MRs
commits	Conventional Commits en profundidad
Catálogo de skills	Skills de Claude disponibles

Nota para el TL: ver repo-sandbox-onboarding-setup para preparar el sandbox antes del primer dev.