Git & GitHub – DÍA 5

GitHub profesional: README, Issues, Wiki, Releases y buenas prácticas

(tu repositorio empieza a parecer de verdad profesional)

1. Objetivo del día

Hoy aprenderás a usar GitHub “como un profesional”, aprovechando:

README (tu carta de presentación)
Issues (gestión de tareas y bugs)
Wiki (documentación viva del repositorio)
Releases (versiones estables de tus scripts)
Licencia, etiquetas y buenas prácticas
Organización del repositorio

Con esto tu repo será fácil de entender, de mantener y de colaborar.

2. README.md: imprescindible y obligatorio

El README es la página de inicio de tu repositorio.
Es lo primero que ve cualquiera.

Debe incluir, como mínimo:

✔ 1. Título del proyecto

# Mis Scripts de Automatización

✔ 2. Descripción breve

Colección de scripts Bash, Python y utilidades para automatización y monitorización.

✔ 3. Cómo usarlo

./backup.sh
./healthcheck.sh servidor.txt

✔ 4. Requisitos

Bash
Python
Linux

✔ 5. Ejemplos

Capturas o comandos.

✔ 6. Estructura del repositorio

/bash
/python
/logs

✔ 7. Notas de seguridad

⚠ No incluir credenciales ni datos sensibles.

¿Por qué se llama `README.md`?

El archivo principal de cualquier repositorio suele llamarse README (“léeme”).
GitHub lo muestra automáticamente en la página principal del proyecto.

La extensión .md significa Markdown.

➡️ Markdown es un formato de texto muy simple que permite poner títulos, listas, código, enlaces e imágenes sin necesidad de Word ni HTML.

Ejemplo en Markdown:

# Título grande

## Sección

- Punto 1
- Punto 2

Código:

echo "Hola"
Enlace: [Mi web](https://example.com)

✍️ Mini guía rápida de Markdown

Los básicos que necesita alguien que empieza:

# → título
## → subtítulo
- → lista
«` código «` → para bloques de comandos
**negrita**
[texto](url) → enlace
![alt](imagen.png) → imagen

Con eso puede hacer un README limpio sin aprender nada más.

Enlace recomendado

👉 Tutorial oficial y súper simple:
https://www.markdownguide.org/basic-syntax/

💡 TIP PROFESIONAL

Un buen README convierte tu repositorio en algo útil incluso para ti dentro de un año.

3. Issues: tu sistema de tareas y preguntas

Los “Issues” son:

tareas pendientes
ideas
mejoras
preguntas
bugs

Crear un issue:

GitHub → pestaña Issues → New issue

Ejemplos:

“Añadir script de backup incremental”
“Mejorar documentación del healthcheck”
“Refactorizar check_dns”

Los issues convierten tu repo en un proyecto vivo.

4. Wiki: documentación extendida

El Wiki es perfecto para:

manuales
procedimientos
instrucciones largas
histórico de cambios
mini tutoriales

Ejemplo de páginas útiles:

“Cómo usar este repositorio”
“Mejores prácticas de Bash”
“Estándares de scripts”
“Templates de README”

Puedes crear páginas fácilmente desde la pestaña Wiki.

⚠️ Nota importante sobre la Wiki en GitHub

La Wiki solo está disponible automáticamente si tu repositorio es público.
Si el repositorio es privado, GitHub mostrará un mensaje como:

“Upgrade or make this repository public to enable Wikis”

En ese caso, tienes dos opciones:

Hacer el repositorio público → la Wiki se activa gratis.
Mantenerlo privado → necesitas un plan de pago (Pro/Team) para usar la Wiki.

Recomendación para este mini tutorial

Para seguir esta práctica sin líos:

➡️ Usa un repositorio público (puedes borrarlo después si no quieres dejarlo abierto).
Así podrás acceder a la Wiki desde la pestaña Wiki sin que GitHub pida upgrade.

5. Releases: versiones estables del proyecto

En GitHub, una Release es una versión empaquetada de tu software.

Para scripts es MUY útil:

publicar “v1.0”, “v1.1”, etc.
decir qué cambió
permitir descargar un zip limpio de esa versión

Crear una release:

GitHub → Releases → Draft a new release

Pon:

Tag: v1.0
Title: “Primera versión estable”
Notas de cambios

6. Licencia del repositorio

Si el repo es público, debes elegir licencia:

MIT → muy abierta
GPL → copyleft
Apache → profesional
“All rights reserved” → cerrado

GitHub te ofrece un selector de licencias.

7. Buenas prácticas profesionales

✔ Estructura clara de carpetas

/bash
/python
/logs
/docs

✔ Nombres limpios

healthcheck.sh
backup.sh
procesar_logs.py

✔ Commits con mensajes claros

Añade función check_disk al script healthcheck

✔ README completo

✔ Issues abiertos siempre visibles

✔ Releases por versión

✔ No subir archivos pesados o innecesarios

8. Práctica guiada (20–30 minutos)

1️⃣ Crear un README decente

Incluye:

título
descripción
estructura
ejemplos
notas de seguridad

Cómo se crea un README realmente

Opción 1 — En local (la más típica y profesional)

En tu ordenador creas el archivo:

nano README.md

o usando VS Code, Notepad++, Vim… lo que uses normalmente.

Escribes tu contenido Markdown.
Lo añades al repositorio:

git add README.md
git commit -m "Añadir README inicial"
git push

👉 Esta es la forma que usa el 90% de la gente que trabaja con Git.

Opción 2 — Directamente desde GitHub

Si el repo ya existe en GitHub, puedes:

Entrar al repositorio
Pulsar Add file → Create new file
Nombrarlo README.md
Escribirlo en el editor web
Guardar con un commit

👉 Muy cómodo si no tienes la copia local todavía.

Opción 3 — GitHub ya te crea uno si marcas la casilla

Cuando creas el repositorio nuevo desde GitHub tienes una casilla:

✔ Add a README file

Si la marcas, GitHub te genera un README vacío para que luego tú lo edites.

2️⃣ Crear al menos 3 issues

“Añadir script X”
“Mejorar documentación”
“Refactorizar función Y”

3️⃣ Crear una página en el Wiki

“Guía básica de scripts del repositorio”

4️⃣ Crear tu primera Release

tag v1.0
notas breves
subir los scripts actuales

Todo esto te hace parecer un profesional REAL.

9. Checklist del Día 5

README completo
Issues creados
Wiki creada
Release creada
Licencia elegida
Repositorio ordenado
Buenas prácticas aplicadas

Si está todo marcado → Día 5 superado.

10. Ejercicio sugerido

En tu repositorio:

Crear un archivo VERSION.md
Añadir la historia de versiones
Crear una Release con Tag v1.0
Subir capturas del funcionamiento de algún script
Crear un issue con mejoras futuras

11. Día 5 completado

Tu repositorio ya tiene estructura, documentación y herramientas profesionales.
Mañana llega algo muy práctico y moderno:

👉 Día 6 – VS Code + Git: flujos visuales, commits gráficos, staging visual, extensiones, GitLens.

VS Code te hará la vida más fácil con Git.