🏯 El Origen del Pergamino: Repositorios, README.md y .gitignore

“Un pergamino en blanco es una aldea sin historia. Un pergamino bien escrito es el mapa que guía a las generaciones futuras.” - Maestro Sensei

🎯 La Filosofía del Pergamino

Todo shinobi necesita un lugar sagrado donde guardar sus técnicas. En el mundo del código, ese lugar es el repositorio. Pero un repositorio sin documentación es como una aldea sin señales: nadie sabrá qué tesoros guarda ni cómo usarlos.

El README.md es la fachada de tu aldea: lo primero que ven los visitantes. El .gitignore es tu Jutsu de Ocultación: protege secretos y evita que basura innecesaria manche tu historial.

📜 El Camino del Conocimiento

Parte 1: Crear tu Primera Aldea (Repositorio)

Un repositorio es un contenedor versionado de tu proyecto. Puede vivir localmente (tu máquina) o remotamente (GitHub).

Crear un repositorio local:

# Navega a tu directorio de proyectos
cd ~/proyectos

# Crea una nueva carpeta para tu aldea
mkdir mi-primera-aldea
cd mi-primera-aldea

# Inicializa el repositorio (crea el pergamino mágico .git/)
git init

# Verifica el estado
git status

Explicación técnica:

  • git init crea una carpeta oculta .git/ que contiene toda la magia: historial de cambios, referencias, configuración.
  • Esta carpeta ES tu repositorio. Sin ella, solo tienes archivos normales.

Crear un repositorio en GitHub:

  1. Ve a github.com y haz clic en “New repository”
  2. Dale un nombre descriptivo: landing-page-ninja (usa kebab-case)
  3. Importante: Marca “Add a README file” solo si es un proyecto desde cero
  4. Elige visibilidad: Public (código abierto) o Private (proyecto secreto)
  5. Click en “Create repository”

Conectar tu aldea local con GitHub:

# Añade el repositorio remoto (origin = alias del URL)
git remote add origin https://github.com/tu-usuario/mi-primera-aldea.git

# Verifica la conexión
git remote -v

# Sube tu código al templo de GitHub
git push -u origin main

Parte 2: El README.md - La Fachada de tu Aldea

El README es un archivo Markdown (.md) que describe tu proyecto. Es lo primero que leen reclutadores, colaboradores y usuarios.

Anatomía de un README profesional:

# 🏯 Nombre del Proyecto

![Badge de Estado](https://img.shields.io/badge/estado-en%20desarrollo-yellow)
![Licencia](https://img.shields.io/badge/licencia-MIT-blue)

## 📖 Descripción

Una aplicación web para gestionar misiones ninjas. Permite crear, asignar y completar tareas con un sistema de rangos (D, C, B, A, S).

## ✨ Características

- ✅ Sistema de autenticación con JWT
- ✅ Dashboard interactivo con gráficas
- ✅ API RESTful documentada con Swagger
- 🚧 Notificaciones en tiempo real (en desarrollo)

## 🚀 Instalación Rápida

\`\`\`bash
# Clona el repositorio
git clone https://github.com/tu-usuario/proyecto-ninja.git

# Instala dependencias
npm install

# Configura variables de entorno
cp .env.example .env

# Levanta el servidor de desarrollo
npm run dev
\`\`\`

## 🛠️ Tecnologías Usadas

| Tecnología | Propósito |
|------------|-----------|
| React 18   | UI Library |
| Node.js    | Backend   |
| PostgreSQL | Base de datos |
| Docker     | Contenedores |

## 📸 Capturas de Pantalla

![Dashboard Principal](./docs/screenshots/dashboard.webp)

## 🤝 Contribuir

Las contribuciones son bienvenidas. Por favor, lee [CONTRIBUTING.md](CONTRIBUTING.md) antes de hacer un Pull Request.

## 📝 Licencia

Este proyecto está bajo la licencia MIT. Ver [LICENSE](LICENSE) para más detalles.

## 👤 Autor

**Abraham Pech** - [GitHub](https://github.com/abrahampech) | [LinkedIn](https://linkedin.com/in/abrahampech)

Elementos clave que NUNCA deben faltar:

  1. Título descriptivo con emoji (opcional pero memorable)
  2. Badges (shields.io): estado del build, cobertura de tests, licencia
  3. Descripción clara en 1-2 párrafes (el “elevator pitch”)
  4. Instalación paso a paso (asume que el lector no sabe nada)
  5. Stack tecnológico (lista o tabla)
  6. Capturas de pantalla o GIFs (una imagen vale más que 1000 líneas)
  7. Licencia y autor

Pro tip para Markdown:

  • Usa ## Nivel 2 para secciones principales (Nivel 1 es solo el título)
  • Los bloques de código deben tener el lenguaje: ```bash, ```javascript, etc.
  • Las imágenes pueden ser locales ![Alt](./ruta.webp) o URLs externas

Parte 3: El .gitignore - Jutsu de Ocultación

El archivo .gitignore le dice a Git qué archivos NO rastrear. Esto es crítico para:

  1. Seguridad: No subir credenciales (.env, claves API)
  2. Eficiencia: No versionar archivos generados (node_modules/, dist/)
  3. Limpieza: Evitar archivos del sistema (.DS_Store, Thumbs.db)

Crear un .gitignore desde cero:

# Crea el archivo (el punto inicial lo hace oculto en Unix)
touch .gitignore

Contenido de un .gitignore para proyecto Node.js/React:

# Dependencias
node_modules/
package-lock.json  # Opcional, algunos equipos lo versionan

# Variables de entorno (¡CRÍTICO!)
.env
.env.local
.env.production

# Archivos de build
dist/
build/
.next/
.cache/

# Logs
npm-debug.log*
yarn-debug.log*
logs/
*.log

# Sistema operativo
.DS_Store        # macOS
Thumbs.db        # Windows
*.swp            # Vim
*~               # Emacs

# IDEs
.vscode/         # VS Code (o versionarlo si todos usan lo mismo)
.idea/           # JetBrains
*.sublime-*      # Sublime Text

# Testing
coverage/
.nyc_output/

# Otros
.tmp/
temp/

Patrones avanzados:

# Ignorar TODOS los .txt en cualquier carpeta
**/*.txt

# Excepto README.txt (el ! lo niega)
!README.txt

# Ignorar carpetas específicas
logs/
temp/

# Ignorar archivos que terminen en .log
*.log

# Ignorar TODO dentro de uploads/ pero mantener la carpeta
uploads/*
!uploads/.gitkeep

Truco ninja: Si ya subiste un archivo por error (ej. .env), debes eliminarlo del historial:

# Dejar de rastrearlo (pero NO lo borra de tu disco)
git rm --cached .env

# Añádelo al .gitignore
echo ".env" >> .gitignore

# Confirma el cambio
git add .gitignore
git commit -m "chore: eliminar .env del historial"

Plantillas de .gitignore según lenguaje:

Usa gitignore.io para generar automáticamente según tu stack:

# Ejemplo: Node.js + React + macOS
curl -L https://www.toptal.com/developers/gitignore/api/node,react,macos > .gitignore

💡 Jutsu Secreto: Plantillas de README Épicas

No reinventes la rueda. Usa generadores y plantillas profesionales:

  1. readme.so: Editor visual de README con preview en vivo
  2. makeareadme.com: Guía oficial de buenas prácticas
  3. awesome-readme: Galería de READMEs increíbles

Estructura de carpetas profesional desde el inicio:

mi-proyecto/
├── .git/
├── .gitignore
├── README.md
├── LICENSE
├── .env.example          # Plantilla de variables (SIN valores reales)
├── src/                  # Código fuente
│   ├── components/
│   ├── utils/
│   └── index.js
├── docs/                 # Documentación extra
│   └── screenshots/
├── tests/                # Pruebas unitarias
└── package.json

Comando ninja para crear estructura rápida:

mkdir -p src/{components,utils} docs/screenshots tests
touch README.md .gitignore .env.example LICENSE
git init

🎯 Reto Ninja del Tema

Misión: Crear tu aldea profesional desde cero

  1. Crea un repositorio local llamado portafolio-ninja
  2. Inicializa Git y haz tu primer commit con un mensaje semántico: feat: inicializar proyecto
  3. Crea un README.md con:
    • Título y descripción de tu portafolio
    • 3 proyectos que planeas incluir (pueden ser futuros)
    • Stack tecnológico que usarás
    • Al menos 2 badges de shields.io
  4. Crea un .gitignore que incluya:
    • node_modules/
    • .env
    • Archivos de tu sistema operativo
  5. Sube todo a GitHub (crea el repo remoto primero)
  6. BONUS: Añade una imagen o GIF al README (puede ser un placeholder)

Criterios de éxito:

  • ✅ El README se ve formateado correctamente en GitHub
  • ✅ El .gitignore previene que node_modules/ se suba (instala cualquier paquete npm para probar)
  • ✅ El historial tiene al menos 3 commits con mensajes descriptivos

📚 Recursos Adicionales

Siguiente Pergamino: 3.2 Las Ramas del Destino - branch, checkout, merge

¿Completaste el reto? ¡Comparte tu repositorio en Discord con el hashtag #PergaminoNinja! 🥷📜