Contribuyendo

Esta página aborda los aspectos técnicos de la contribución a la wiki: obtener el repositorio, realizar cambios y lograr su integración.

Requisitos Previos

Tip

Se requiere estar familiarizado con los conceptos básicos de git: si eres nuevo en estas herramientas, visita git para principiantes absolutos para obtener una introducción completa.

• Programas git y python instalados localmente.
• Una cuenta en nuestra instancia de Forgejo con acceso al repositorio de la wiki.
• (Opcional pero recomendado) un editor compatible con Markdown que ofrezca vista previa en tiempo real.

El Flujo de Trabajo

Gracias a la relativa simplicidad del proyecto, operamos bajo un flujo de trabajo basado en clonación, creación de ramas (branching), commit e integración (merge):

1. Clonación (Clone): obtén una copia local del último commit de esta wiki.
2. Creación de la Rama (Branch): crea una rama a partir de nuestra copia local e implementar los cambios.
3. Haz tus Cambios: realiza los cambios pertinentes dentro del alcance establecido.
4. Confirma tus Cambios (Commit): guarda tu trabajo en un punto que contiene todos los cambios realizados.
5. Sube tus Cambios (Push): sube tu trabajo al servidor remoto para que el equipo este al tanto de tu trabajo.
6. Integra tus Cambios Mediante una Pull Request (PR): envía los commits para su revisión, quedando pendiente de la aprobación del equipo.

Note

Las ramas, los mensajes de tus commits y las pull/merge requests; pasos 2, 4 y 5) siguen la convención de nombres de Conventional Commits para garantizar la mayor semántica posible y facilitar los procesos de CI/CD.

1. Clona el Repositorio (Clone)

Primero, clona el repositorio utilizando git en la terminal de tu preferencia:

HTTPSSSH

git clone https://git.compassconsulting.cl/compass/wiki.git
# luego entra en el directorio del repositorio
cd wiki

git clone ssh://git@git.compassconsulting.cl/compass/wiki.git
# luego entra en el directorio del repositorio
cd wiki

2. Crear una Rama (Branch)

Crea una rama con un nombre que describa la tarea que estás realizando:

git switch -c <nombre-de-la-rama>

Nombre de rama

Añade a la rama el mismo prefijo que usarás en tu commit (por ejemplo: docs/, fix/, feat/), seguido de una descripción breve separada por guiones.

Ten en cuenta que el nombre de la rama debe estar directamente relacionado con el alcance de tu trabajo (p. ej.: el trabajo para este documento se realizó en la rama docs/getting-started porque también reestructuré toda la sección "Getting Started").

Cualquier cambio que quede fuera de dicho alcance debe separarse adecuadamente o realizarse en una rama más general.

3. Realiza tus Cambios

Crea o edita los archivos correspondientes utilizando el editor de tu elección y configura un servidor de desarrollo local para previsualizar los cambios.

Asegúrate de estar en la carpeta del proyecto

Debes encontrarte en el directorio del proyecto (wiki/) para que los siguientes pasos funcionen correctamente.

Dependencias

Podemos instalar todas las dependencias sin afectar la compatibilidad del sistema utilizando un entorno virtual de Python (venv):

python -m venv .venv                # instalamos el entorno virtual
source .venv/bin/activate           # lo activamos
pip install -r requirements.txt     # instalamos todos los requisitos previos para ejecutar MkDocs

Servidor de desarrollo

Una vez instaladas las dependencias, podemos ejecutar mkdocs localmente para visualizar los cambios a medida que los realizamos:

mkdocs serve --livepreview

Esto iniciará el servidor de desarrollo en localhost:8000 y recargará la página automáticamente al guardar cualquier cambio. Puedes cerrar el servidor de desarrollo presionando ++ctrl+cm+

4. Confirma tus Cambios (Commit)

Utilizamos Conventional Commits para los mensajes de confirmación. El formato es:

<tipo>(ámbito opcional): <resumen breve>

Todo el contenido del mensaje debe escribirse en minúsculas y sin punto final. El ámbito (scope) es opcional, pero debe coincidir con el nombre de tu rama (por ejemplo: si la rama es docs/getting-started, el ámbito sería getting-started). Para nuestros fines, puedes limitarte a un conjunto reducido de tipos más relevantes para la wiki:

Tipo	Uso
docs	Creación o edición de páginas de documentación.
fix	Corrección de errores en una página existente.
feat	Adición de una nueva sección o funcionalidad a la propia wiki.
chore	Tareas de mantenimiento ajenas al contenido (configuración, CI, dependencias).

git add <archivo(s) modificado(s)>
git commit -m "<tipo>: <mensaje descriptivo detallando tu trabajo>"

La nomenclatura es más importante que la lista de tipos

No te preocupes por memorizar todos los tipos posibles. Si alguna vez tienes dudas sobre si se aplica algo más específico, consulta la especificación completa.

5. Envía tu Rama (Push)

Sube los commits que has realizado al repositorio remoto (upstream) para que el equipo pueda ser notificado de tus cambios.

git push -u origin <rama que creaste>

6. Abre una Pull Request (PR)

En Forgejo, abre una PR desde tu rama hacia main. Asigna a la PR un título que siga la misma convención que tu commit y describe brevemente qué cambió y por qué en la sección de descripción.

Tip

Si estás abriendo una PR de tipo fix:, asegúrate de hacer referencia a cualquier issue vinculado a ella utilizando las palabras clave de GitHub, ya sea en los comentarios o en los mensajes de los commits.

Una vez abierta, otro miembro del equipo revisará tu trabajo y podría solicitar cambios en el código o la documentación antes de fusionarlos con la rama main. Cuando tus cambios sean aprobados, la PR se fusionará e implementará en la siguiente iteración de la wiki.

En caso de que se detecten problemas con tus cambios más adelante, es posible que se reviertan los commits de la PR y se genere una discusión adicional en el hilo de la misma o en un issue separado.

Después de la Fusión

Una vez que tu solicitud de extracción se fusiona con main, la build pipeline la procesa automáticamente y publica la wiki actualizada, sin necesidad de realizar pasos manuales por tu parte.