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.

🎯 Esto es el onboarding — práctica con el repo sandbox wiedii-dev-onboarding. Para crear un proyecto/repositorio real desde cero (paso a paso y qué tener en cuenta), ver repo-setup.

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.

📖 Mini-glosario (términos que verás en esta guía):

terminal / shell / zsh — la app de línea de comandos y el programa que interpreta lo que escribes (en macOS, zsh).

CLI — Command-Line Interface: un programa que se usa desde la terminal.

~ — atajo de "tu carpeta personal" (p. ej. ~/Docker = la carpeta Docker dentro de tu usuario).

PATH — la lista de carpetas donde el sistema busca los programas que ejecutas.

repo / repositorio — la carpeta de un proyecto versionada con Git.

clone — descargar una copia local de un repositorio.

commit — guardar un cambio en el historial de Git, con un mensaje que lo describe.

push / pull — subir tus commits al servidor / traer los del servidor.

branch (rama) — una línea de trabajo paralela dentro del repo.

MR (Merge Request) — la propuesta de integrar tu rama; el equipo la revisa antes de fusionarla.

runtime — el programa que ejecuta un lenguaje (p. ej. Node ejecuta JavaScript).

gestor de paquetes — instala y actualiza las librerías de un proyecto (p. ej. Bun).

hook — un programa que Git dispara solo en un momento concreto (p. ej. antes de cada commit); tú no lo ejecutas.

lockfile — archivo que fija las versiones exactas de las dependencias para que todos instalen lo mismo.

Prerrequisitos

Acceso	Para qué	A quién pedirlo
Cuenta GitLab	Clonar repos, abrir MRs, CI	Infraestructura
Microsoft Teams	Canal del equipo de Desarrollo	TI
Correo corporativo (`@wiedii.co`)	Comunicaciones formales	TI

La cuenta de GitLab y cualquier acceso a servidores los entrega el equipo de Infraestructura. Los accesos corporativos (correo y Teams) los gestiona TI.

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

⚠️ Poder clonar no es poder hacer push. Con rol Reporter puedes git clone/pull, pero al publicar tu rama feature/* GitLab responde You are not allowed to push code to this project. Para completar el onboarding —y para trabajar a diario— necesitas al menos rol Developer en el repo, o que el proyecto esté compartido con tu grupo. Si te sale ese error, pídeselo a tu TL/Infra. Ver repo-sandbox.

Antes de nada: la terminal y cómo seguir este tutorial

Si nunca abriste una terminal, empieza aquí — no hace falta experiencia previa. La terminal (o línea de comandos) es una app donde escribes órdenes de texto y el Mac las ejecuta. Es la herramienta principal de esta guía.

Abrirla: pulsa Cmd + Espacio (Spotlight), escribe Terminal y pulsa Enter. Más adelante instalarás Warp, la terminal por defecto de Wiedii, y usarás esa.
El prompt: verás una línea que termina en % (o $) esperando tu orden. Ahí escribes.
Ejecutar un comando: copia una línea, pégala en la terminal (Cmd + V) y pulsa Enter.
Los bloques de código de esta guía suelen tener varias líneas = varios comandos: ejecútalos uno por uno, en orden, salvo que se indique lo contrario. Las líneas que empiezan con # son comentarios (explicaciones), no se ejecutan.
Las contraseñas son invisibles: cuando un comando te pida una contraseña o passphrase, no verás nada mientras escribes (ni puntos ni asteriscos). Es normal — escribe y pulsa Enter.

Cómo crear o editar un archivo de configuración

Varios pasos de esta guía crean o editan archivos de configuración. Muchos empiezan con un punto (~/.zshrc, ~/.ssh/config) y por eso están ocultos por defecto. Tienes dos formas — usa la que te resulte más cómoda:

Opción A — Terminal con nano (recomendada; sirve para todos los archivos de esta guía):

Abre la terminal (Warp).
Escribe nano seguido de la ruta del archivo. Si el archivo no existe, se crea al guardar:
```
nano ~/.zshrc
```
Dentro de nano, escribe o pega el contenido.
Guarda con Ctrl + O y luego Enter.
Sal con Ctrl + X.

Algunos pasos usan en su lugar un bloque cat > archivo << 'EOF' … EOF: eso crea el archivo completo de una sola vez desde la terminal — copia y pega el bloque entero (desde cat hasta el EOF final) y pulsa Enter. Si prefieres, puedes crear ese mismo archivo con nano y pegar solo el contenido de adentro.

Opción B — Finder (con archivos ocultos visibles):

Abre Finder.
Pulsa Cmd + Shift + . (punto) para mostrar los archivos ocultos — los que empiezan con . aparecen, algo más tenues. (Es un interruptor: pulsa otra vez para volver a ocultarlos.)
Para ir directo a una carpeta por su ruta: Cmd + Shift + G, escribe la ruta (p. ej. ~/.config) y pulsa Enter.
Abre el archivo con tu editor (con VS Code: clic derecho → Abrir con → Visual Studio Code). Para crear un archivo nuevo desde cero es más simple la Opción A.

💡 Cuando un paso diga "crea/edita ~/ruta/archivo", vuelve aquí si no recuerdas cómo. Toda esta guía asume la Opción A (terminal + nano).

Validaciones previas (Fase 0)

Antes de instalar nada, confirma el estado de la máquina:

echo $SHELL   # ✅ /bin/zsh
uname -m      # ✅ arm64 (Apple Silicon M1/M2/M3/M4) o x86_64 (Intel)
whoami        # tu usuario local

💡 Valida antes de seguir. Cada fase termina con una comprobación (# ✅ ...). Si el resultado no se parece al esperado, no avances: resuelve primero (ver Troubleshooting) o pide ayuda compartiendo la salida de diagnóstico del final.

La filosofía de instalación en Wiedii

Homebrew instala herramientas del sistema. mise gestiona versiones por proyecto. ⚠️ Cualquier versión de herramienta mencionada en esta guía debe verificarse antes de usarse — puede estar desactualizada. Ver politicas-core.

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

De un vistazo — qué hace cada herramienta:

Herramienta	Para qué sirve en Wiedii
Homebrew	Instala herramientas del sistema: Git, glab, OrbStack, VS Code, Warp, utilidades CLI.
mise	Gestiona versiones de runtimes y herramientas por proyecto.
Bun	Runtime/gestor JS/TS: instala dependencias y corre scripts.
wietoo-cli	Asistente y validador de commits (Conventional Commits). Reemplaza a czg/commitlint.
Git	Control de versiones.
Git Flow	Flujo estándar de ramas: `main`, `develop`, `feature/`, `release/`, `hotfix/*`.
glab	CLI de GitLab: MRs, pipelines, autenticación.
Lefthook	Corre validaciones automáticas en cada commit (linters, escaneo de secretos).
OrbStack	Runtime de contenedores autorizado.

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 Instalar y configurar mise global

Instalar mise (gestiona versiones por proyecto) y crear el config global con los runtimes estándar de Wiedii. El bloque cat > … << 'EOF' crea el archivo ~/.config/mise/config.toml de una sola vez — copia y pega el bloque entero (ver Cómo crear o editar un archivo):

brew install mise

mkdir -p ~/.config/mise

cat > ~/.config/mise/config.toml << 'EOF'
[tools]
bun    = "1.3.14"
node   = "24.16.0"
pnpm   = "11.6.0"
python = "3.14.6"
uv     = "0.11.21"

[settings]
experimental = true
lockfile = true
all_compile = false
EOF

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

⚠️ mise todavía no está activado en esta terminal — la activación permanente (todas las terminales, vía .zprofile) se configura más adelante, en el paso 1.4. Para que los siguientes comandos ya resuelvan por mise en esta sesión, actívalo temporalmente:
eval "$(mise activate zsh --shims)"

Verificar:

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

Detalle completo (activación permanente, mise.toml por proyecto, hooks): mise y configuracion-zsh (paso 1.4).

1.3 Herramientas esenciales de desarrollo

# 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 — Rust CLIs preferidas + zinit (gestor de plugins del shell, se activa en 1.4)
brew install jq yq bat eza fd ripgrep sd tree starship zinit gping tlrc

# Utilidades base del sistema (Nivel 1 "para todos" en [[herramientas-por-rol]])
# coreutils da gtimeout/gsed que algunos hooks y tareas de mise necesitan en macOS
brew install coreutils htop wget rsync git-filter-repo mas mole

# GPG — firma de commits (se configura en 1.5.1; obligatoria en Wiedii)
brew install gnupg pinentry-mac

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

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

⚠️ Abrir OrbStack manualmente al menos una vez (Spotlight → "OrbStack" → Enter) antes de continuar. Sin este paso el socket Docker no queda configurado y docker context show (más abajo) no va a devolver orbstack. Detalle: orbstack.

# Editor y terminal por defecto
brew install visual-studio-code   # editor POR DEFECTO (Zed opcional, por rendimiento)
brew install warp                 # terminal POR DEFECTO

Editor: VS Code es el por defecto; Zed (brew install zed) se recomienda si quieres más rendimiento a cambio de comodidades como el manejo de git dentro del editor. Terminal: Warp es el por defecto. Lista completa por rol en herramientas-por-rol.

⚠️ Selecciona el Nerd Font en Warp (si no, el prompt se verá con cuadros □ en lugar de iconos): abre Warp → Settings → Appearance → Font → elige "JetBrainsMono Nerd Font". Instalar la fuente con brew no la activa sola; hay que seleccionarla. Detalle en configuracion-editores y herramientas-rust.

✏️ VS Code — desactiva "Format on Save". El formato corre en el commit (el hook re-formatea y re-stagea), así que formatear también en local genera diffs de ida y vuelta. En VS Code: Cmd + , → busca "format on save" → desmárcalo. Detalle y settings.json recomendado en configuracion-editores. (Esto no bloquea commits — es solo para diffs limpios.)

✏️ ¿Cómo se edita un archivo de configuración? Varios pasos más abajo editarás archivos como ~/.zshrc o ~/.ssh/config. Con VS Code instalado, ábrelos desde la terminal con code <ruta> (p. ej. code ~/.zshrc), edita y guarda con Cmd + S. Los archivos que empiezan con . están ocultos en Finder, pero el editor los abre sin problema. Detalles en configuracion-editores.

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)

Wiedii usa tres archivos de shell, cada uno con una responsabilidad. Créalos/edítalos con nano (ver Cómo crear o editar un archivo) y copia el contenido completo de cada uno desde configuracion-zsh — está listo para pegar tal cual:

Archivo	Qué va ahí	Cómo abrirlo
`~/.zshenv`	PATH base del sistema	`nano ~/.zshenv`
`~/.zprofile`	Activación de brew, mise, OrbStack	`nano ~/.zprofile`
`~/.zshrc`	Prompt (starship), completions (glab, kubectl…), aliases, `typeset -U PATH`, `GPG_TTY`	`nano ~/.zshrc`

⚠️ ~/.zprofile es donde queda la activación permanente de mise (eval "$(mise activate zsh --shims)", incluida en el contenido de configuracion-zsh). El paso 1.2 solo la activó temporalmente para esa terminal; al copiar el .zprofile completo aquí, queda activa en todas las terminales nuevas.

Crea también el tema del prompt — ~/.config/starship.toml. Sin este archivo, tu .zshrc apunta a un prompt que no existe y Starship cae a su estilo por defecto (no el de Wiedii):

nano ~/.config/starship.toml   # pega el contenido de la sección de starship de [[herramientas-rust]]

El bloque TOML completo (tema Gruvbox powerline) está en herramientas-rust. Cópialo tal cual.

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
echo $STARSHIP_CONFIG    # ✅ /Users/<tu-usuario>/.config/starship.toml
bun --version            # ✅ 1.3.14 — confirma que mise quedó activo de forma permanente

El prompt debe verse con el tema Wiedii (segmentos de colores con iconos). Si ves cuadros □, falta seleccionar el Nerd Font en Warp (paso 1.3); si el prompt es el genérico, falta crear ~/.config/starship.toml.

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

# Identidad — el email debe coincidir con el de tu clave GPG (paso 1.5.1) y tu cuenta GitLab
git config --global user.name  "Tu Nombre"
git config --global user.email "tunombre@wiedii.co"

# Merge y rebase
git config --global merge.ff false
git config --global pull.rebase false
git config --global fetch.prune true       # limpia refs de ramas ya borradas en GitLab

# Normalización de fin de línea (LF en todo)
git config --global core.autocrlf false
git config --global core.eol lf
git config --global core.ignorecase false

# Módulos Go privados de Wiedii (wietoo vive en el grupo interno wiedii-registry):
# reescribe la URL para autenticar por SSH. Una sola vez por máquina.
git config --global url."git@gitlab.wiedii.co:".insteadOf "https://gitlab.wiedii.co/"

⚠️ La línea insteadOf no es opcional. Sin ella, el mise run setup de la Fase 2 (y de cualquier repo Wiedii que use wietoo) falla al descargar el binario con un error de red/autenticación — es un módulo Go de un repo privado. Ver wietoo-cli (sección "wietoo vive en un repositorio privado").

La lista completa de config git de Wiedii (con explicación de cada valor) está en politicas-core. La firma GPG se configura en el paso siguiente.

1.5.1 Firma de commits con GPG (obligatoria)

En Wiedii todos los commits y tags deben ir firmados con GPG — aparecen con el badge ✅ Verified en GitLab. gnupg y pinentry-mac ya se instalaron en el paso 1.3. Haz esta configuración completa ahora, antes de tu primer commit: si activas la firma sin la clave lista, cada commit falla con gpg failed to sign the data.

El detalle de cada paso, la renovación de la clave y el troubleshooting completo están en configuracion-gpg. Aquí va la secuencia mínima para dejarlo funcionando y verificado.

1. Genera tu clave (es interactivo). Elige RSA y RSA, tamaño 4096, caducidad 2y, tu nombre, y el mismo email que pusiste en user.email (si no coinciden, GitLab marcará los commits como Unverified):

gpg --full-generate-key

2. Copia el ID de tu clave — es la parte después de rsa4096/ en la línea sec:

gpg --list-secret-keys --keyid-format=long

3. Regístrala en git (reemplaza <TU_ID> por el ID del paso 2):

git config --global user.signingkey <TU_ID>

4. Configura el agente GPG. Primero confirma la ruta de pinentry-mac según tu chip:

which pinentry-mac
# Apple Silicon → /opt/homebrew/bin/pinentry-mac   ·   Intel → /usr/local/bin/pinentry-mac

Crea ~/.gnupg/gpg-agent.conf (el bloque cat > … << 'EOF' lo crea de una vez — ver Cómo crear o editar un archivo). Si tu Mac es Intel, corrige la ruta de pinentry-program:

mkdir -p ~/.gnupg && chmod 700 ~/.gnupg

cat > ~/.gnupg/gpg-agent.conf << 'EOF'
pinentry-program /opt/homebrew/bin/pinentry-mac
use-standard-socket
allow-loopback-pinentry
default-cache-ttl 28800
max-cache-ttl 86400
EOF

gpgconf --kill gpg-agent && gpgconf --launch gpg-agent

GPG_TTY ya quedó exportado en tu .zshrc (paso 1.4). Si abriste esta terminal antes de aplicar el .zshrc, corre exec zsh.

5. Activa la firma automática:

git config --global commit.gpgsign true
git config --global tag.gpgsign true

6. Exporta tu clave pública y regístrala en GitLab (necesario para el badge Verified):

gpg --armor --export <TU_ID>

Copia toda la salida (desde -----BEGIN… hasta -----END…) y pégala en gitlab.wiedii.co → tu perfil → Preferences → GPG Keys → Add key.

7. Verifica que firma de verdad (en un repo temporal, aún no has clonado ninguno):

mkdir -p /tmp/gpg-test && cd /tmp/gpg-test && git init -q
git commit --allow-empty -m "test: verificar firma GPG"
git log --show-signature -1     # ✅ "Good signature from Tu Nombre <tunombre@wiedii.co>"
cd ~ && rm -rf /tmp/gpg-test

Si ves Good signature, la firma funciona. Si falla con gpg failed to sign the data, revisa la ruta de pinentry-program (paso 4) y que GPG_TTY esté exportado — troubleshooting en configuracion-gpg.

1.6 Clave SSH para GitLab

# Generar si no tienes una (te pedirá un passphrase — ponlo, no lo dejes vacío;
# recuerda: al escribir la passphrase la terminal no muestra nada, es normal)
ssh-keygen -t ed25519 -C "tunombre@wiedii.co"

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

Guardar el passphrase en el Keychain de macOS (el passphrase es la contraseña que protege tu llave privada; al guardarlo, no te lo vuelve a pedir en cada reinicio):

# Carga la llave en el agente y guarda el passphrase en el Keychain
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Crear/actualizar ~/.ssh/config para que la llave se cargue sola desde el Keychain. Ábrelo con nano ~/.ssh/config (ver Cómo crear o editar un archivo) y pega este contenido:

# ~/.ssh/config
Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

--apple-use-keychain es el flag actual (reemplaza al antiguo -K, deprecado). Con esto + el config, el ssh-agent deja la llave lista, y es la misma llave/agente que VS Code reenvía a un dev container → ahí también funciona sin volver a pedir el passphrase.

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 Configurar y autenticar glab

Configuración estándar Wiedii (antes de autenticar — usa --global, funciona incluso fuera de un repo):

glab config set --global host gitlab.wiedii.co   # CRÍTICO: sin esto glab apunta a gitlab.com y da 401
glab config set --global git_protocol ssh
glab config set --global telemetry false          # obligatorio
glab config set --global glamour_style dark
glab config set -h gitlab.wiedii.co git_protocol ssh
glab config set -h gitlab.wiedii.co api_protocol https

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

glab config get host           # ✅ gitlab.wiedii.co
glab config get telemetry      # ✅ false
glab config get git_protocol   # ✅ ssh

🔐 glab guarda el token en el keychain del sistema. Nunca escribas el token en archivos del vault. Configuración completa (completion en zsh, comandos clave, troubleshooting): glab.

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 trust && mise run setup

mise trust va primero. En un clon nuevo el mise.toml no es de confianza y mise no ejecuta tareas de un config no confiable — por eso se confía antes de correr la tarea (no puede ir dentro de setup, sería circular).

mise run setup hace en orden: instala todas las herramientas del mise.toml → ejecuta lefthook install automáticamente (via [hooks].postinstall) → mise lock → 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

⚠️ mise.lock puede aparecer como modificado tras mise run setup (el paso mise lock lo regenera). Esto significa que si corres git status, Git lo va a listar como un archivo cambiado — aunque tú no lo hayas editado a mano, el comando mise lock sí escribió en él. En el ejercicio de onboarding tu MR solo debe tocar CONTRIBUTORS.md: no incluyas el lockfile → git restore mise.lock (esto deshace el cambio y deja el archivo como estaba). Si dudas si el cambio debe conservarse, consúltalo con tu TL.

⚠️ Si un hook muestra Update available … Run pip3 install -U checkov, no lo ejecutes. Las versiones de herramientas las controla mise + la config del proyecto; actualizar a mano rompe la reproducibilidad. Si hace falta subir de versión, va por el flujo del equipo.

Fase 3 — El flujo de trabajo diario

Git Flow con MRs. Como parte del equipo integras siempre vía MR — el push directo a main/develop está reservado a los mantenedores del proyecto. Ver branch-protection.

ℹ️ No todos los repos usan Git Flow. El sandbox de onboarding sí. Pero algunos proyectos Wiedii (p. ej. esta wiki) usan GitHub Flow: una sola rama main y ramas feature/* directamente contra ella, sin develop. Si tu repo real no tiene develop, es GitHub Flow — revisa su README/CONTRIBUTING. El criterio completo está en git-flow.

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

Formato exacto del nombre de feature/*: feature/<número de tarea>-<máx. 3 palabras> (p. ej. feature/441131-fix-null-id). wietoo check lo valida en el pre-push — regex completa y ejemplos de release/*/hotfix/* en wietoo-cli.

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 0001-max-tres-palabras

# 3. Trabajar y hacer commits
git add .            # mejor aún: añade solo lo que tocaste (p. ej. git add src/archivo.ts)
wietoo 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 [#0001]"

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

⚠️ Nunca git flow feature finish (ni git flow finish). Hace el merge localmente y se salta la protección de ramas y el CI. El flujo correcto siempre termina en MR — git flow publish + revisión. Detalle: git-flow.

Fase 4 — Tu primera contribución

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

echo "- Tu Nombre (@tunombreusuario) — $(date +%Y-%m-%d)" >> CONTRIBUTORS.md
git add CONTRIBUTORS.md
wietoo 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. 🎉

Criterio de éxito del onboarding

El onboarding está completo cuando tienes:

✅ GitLab autenticado por SSH (ssh -T git@gitlab.wiedii.co)
✅ glab autenticado y configurado (glab config get host → gitlab.wiedii.co, telemetry en false)
✅ Prompt con el tema Wiedii — starship + Nerd Font, sin cuadros □ (paso 1.3/1.4)
✅ Firma GPG funcionando: git log --show-signature -1 muestra Good signature y el commit se ve Verified en GitLab (no Unverified)
✅ insteadOf configurado — se confirma solo si mise run setup bajó wietoo sin error de red/auth
✅ Repo clonado en ~/Docker/
✅ mise activo en zsh; bun, lefthook y wietoo funcionando (wietoo version self)
✅ mise run setup sin errores bloqueantes
✅ Rama feature/<id>-slug creada y commit hecho con wietoo commit
✅ Hooks pasando en el commit
✅ Rama publicada y MR abierta contra develop
✅ TL notificado para revisión

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	`wietoo 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

mise run setup falla al descargar wietoo (error de red / autenticación a GitLab): falta el insteadOf del paso 1.5 — wietoo es un módulo Go de un repo privado. Configúralo (una sola vez por máquina) y reintenta:

git config --global url."git@gitlab.wiedii.co:".insteadOf "https://gitlab.wiedii.co/"
mise run setup

Ver wietoo-cli (sección "wietoo vive en un repositorio privado").

command not found: wietoo: mise no instaló las herramientas del proyecto (o falta el insteadOf de arriba):

mise trust && mise run setup
wietoo version self   # ✅

gpg failed to sign the data al hacer commit: GPG quedó a medio configurar (paso 1.5.1):

export GPG_TTY=$(tty)
gpgconf --kill gpg-agent && gpgconf --launch gpg-agent
which pinentry-mac    # la ruta debe coincidir con la de ~/.gnupg/gpg-agent.conf

Ver configuracion-gpg.

El pre-commit hook rechaza el commit:

lefthook run pre-commit   # ver el error exacto → corregir → git add . → wietoo 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.

command not found: bun / command not found: lefthook dentro del proyecto: mise no está activado en tu shell. Actívalo de forma permanente (en .zprofile, igual que el config estándar) y recarga:

echo 'eval "$(mise activate zsh --shims)"' >> ~/.zprofile && exec zsh
bun --version && lefthook --version   # ✅

Ver configuracion-zsh.

glab da 401 Unauthorized: token inválido, expirado o sin scopes. Reloguéate con un token nuevo (api, read_repository, write_repository):

glab auth logout --hostname gitlab.wiedii.co
glab auth login  --hostname gitlab.wiedii.co

failed to write config: not a Git repository al configurar glab: usaste glab config set sin --global fuera de un repo → glab config set --global telemetry false.

You are not allowed to push code to this project: te falta rol Developer en el repo (con Reporter solo se clona). Pídeselo a tu TL/Infra — ver los prerrequisitos.

no pipeline found al ver el pipeline: no siempre es error tuyo; el sandbox puede no tener pipeline, o no dispararse para esa rama/MR. Abre la MR en GitLab y revisa la pestaña de pipelines; si no hay, consúltalo con tu TL:

glab mr list --author @me
glab mr view <numero-mr> --web

Tabla rápida por síntoma

Problema	Causa probable	Solución
`command not found: bun` / `lefthook`	mise no activado en zsh	`echo 'eval "$(mise activate zsh --shims)"' >> ~/.zprofile && exec zsh`
`401 Unauthorized` en glab	Token inválido o sin scopes	Reloguear con token (`api`, `read_repository`, `write_repository`)
`failed to write config: not a Git repository`	`glab config set` sin `--global` fuera de un repo	`glab config set --global …`
`mise.lock` modificado tras setup	`mise run setup` regeneró el lockfile	`git restore mise.lock` (consultar TL si aplica)
`You are not allowed to push code`	Falta rol Developer	Pedir permiso al TL/Infra
`no pipeline found`	CI no configurado o no disparado	Revisar MR en GitLab; consultar TL
`mise run setup` falla al bajar `wietoo`	Falta el `insteadOf` (módulo Go privado)	`git config --global url."git@gitlab.wiedii.co:".insteadOf "https://gitlab.wiedii.co/"`
`command not found: wietoo`	mise no instaló las tools / falta `insteadOf`	`mise trust && mise run setup`
`gpg failed to sign the data`	GPG a medio configurar (paso 1.5.1)	`export GPG_TTY=$(tty); gpgconf --kill gpg-agent && gpgconf --launch gpg-agent`
Commit sale Unverified en GitLab	Email de la clave ≠ `user.email`, o falta registrar la pública	Revisar email de la clave + registrarla en GitLab → GPG Keys
Prompt con cuadros `□`	Nerd Font no seleccionado en Warp	Warp → Settings → Appearance → Font → JetBrainsMono Nerd Font
Prompt genérico (no el tema Wiedii)	Falta `~/.config/starship.toml`	Crearlo con el contenido de herramientas-rust
Passphrase SSH "no coincide"	Se escribieron dos passphrases distintas	Reintentar; la terminal no muestra lo que escribes
`ssh -T` da `Permission denied`	Llave no cargada o no añadida a GitLab	`ssh-add ~/.ssh/id_ed25519`; verificar SSH Keys en GitLab

Antes de pedir ayuda, comparte esta salida

Esto permite a tu TL o compañero diagnosticar rápido en qué carpeta y rama estás, qué cambios tienes y si mise/glab están listos:

pwd; git status; git branch --show-current; git log --oneline -3
git remote -v
mise list; bun --version; lefthook --version; wietoo version self
glab auth status --hostname gitlab.wiedii.co
git config --global --get user.signingkey; git log --show-signature -1 2>&1 | head -3

Referencia por herramienta

Esta guía es un script secuencial para el primer día. Si algo se rompe después — ya no estás siguiendo el onboarding paso a paso — esta tabla es la fuente de verdad de cada herramienta, en un solo lugar:

Herramienta	Para qué	Nota de referencia
Homebrew + mise (filosofía)	Cuándo usar cada uno	gestion-herramientas-brew-mise
mise	Config completa, activación, `mise.toml` por proyecto	mise
Shell (zsh, zinit, PATH, starship)	Los 3 archivos, orden de carga, troubleshooting	configuracion-zsh
Git — config global	Fuente de verdad de cada valor (`pull.rebase`, GPG, etc.)	politicas-core
Firma de commits (GPG)	Generar clave, `gpg-agent`, badge Verified	configuracion-gpg
OrbStack	Primer arranque, dominios `.orb.local`, Kubernetes	orbstack
glab (GitLab CLI)	Config estándar, comandos, troubleshooting	glab
wietoo	Commits, validación de ramas, releases	wietoo-cli
Git Flow completo	Releases, hotfixes, orden de MRs, GitHub Flow	git-flow
lefthook	Git hooks — instalación y config	lefthook
Herramientas por rol	Qué instalar además, según tu rol	herramientas-por-rol

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 plugins	Skills de Claude disponibles

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

Prerrequisitos​

Antes de nada: la terminal y cómo seguir este tutorial​

Cómo crear o editar un archivo de configuración​

Validaciones previas (Fase 0)​

La filosofía de instalación en Wiedii​

Fase 1 — Preparar la máquina​

1.1 Homebrew​

1.2 Instalar y configurar mise global​

1.3 Herramientas esenciales de desarrollo​

1.4 Configurar el shell (zsh)​

1.5 Git — configuración global​

1.5.1 Firma de commits con GPG (obligatoria)​

1.6 Clave SSH para GitLab​

1.7 Configurar y autenticar glab​

Fase 2 — Tu primer repositorio​

Fase 3 — El flujo de trabajo diario​

3.1 Ramas​

3.2 Inicializar git-flow (una vez por clon)​

3.3 Ciclo completo de una feature​

3.4 Comandos shorthand de git-flow-next​

Fase 4 — Tu primera contribución​

Criterio de éxito del onboarding​

Referencia rápida​

Troubleshooting​

Tabla rápida por síntoma​

Antes de pedir ayuda, comparte esta salida​

Referencia por herramienta​

Próximos pasos​